YouVersion Bible Client Documentation

Welcome to the comprehensive documentation for the YouVersion Bible Client library. This library provides both synchronous and asynchronous Python interfaces to interact with all YouVersion API endpoints.

Warning

Important Notice: YouVersion has made their API private, so some functions may not work anymore. This client is maintained for educational and legacy purposes. Please use responsibly.

Overview

The YouVersion Bible Client is a modern Python library that provides:

• Dual Client Support: Both synchronous (SyncClient) and asynchronous (AsyncClient) implementations

• OAuth2 Authentication: Secure authentication using YouVersion’s OAuth2 system

• Comprehensive API Coverage: Access to 55+ API endpoints including: - Bible content and versions - Audio Bible - Moments (highlights, notes, bookmarks, images, badges) - Reading plans - Events - Videos - Friendships - Themes - And much more

• Dynamic Pydantic Models: Automatically generated models from API responses

• Type Safety: Full type hints throughout the codebase

• CLI Support: Command-line interface for easy access to all features

• Python 3.9+: Compatible with Python 3.9 and above

Quick Start

Installation

# Using pip
pip install youversion-bible-client

# Using Poetry
poetry add youversion-bible-client

Basic Usage

Asynchronous Client

import asyncio
from youversion.clients import AsyncClient

async def main():
    async with AsyncClient() as client:
        # Get verse of the day
        votd = await client.verse_of_the_day()
        print(f"Verse: {votd.usfm}")

        # Get moments
        moments = await client.moments(page=1)
        print(f"Found {len(moments)} moments")

asyncio.run(main())

Synchronous Client

from youversion.clients import SyncClient

with SyncClient() as client:
    # Get verse of the day
    votd = client.verse_of_the_day()
    print(f"Verse: {votd.usfm}")

    # Get highlights
    highlights = client.highlights(page=1)
    print(f"Found {len(highlights)} highlights")

Configuration

The client requires YouVersion API credentials. You can provide them in several ways:

1. Environment Variables (Recommended for production):

export YOUVERSION_USERNAME="your_username"
export YOUVERSION_PASSWORD="your_password"

2. `.env` File (Recommended for development):

# Create .env file in project root
YOUVERSION_USERNAME=your_username
YOUVERSION_PASSWORD=your_password

3. Constructor Arguments:

client = AsyncClient(username="user", password="pass")

Documentation Contents

Getting Started:

• Installation
  • Requirements
  • Using pip
  • Using Poetry
  • Verify Installation
  • Dependencies
  • Optional Development Dependencies
  • Troubleshooting
• Quick Start Guide
  • Prerequisites
  • Setting Up Credentials
  • Your First Script
  • Run Your Script
  • Common Operations
  • Next Steps
• Configuration
  • Authentication Methods
  • Environment Variables
  • .env File
  • Constructor Arguments
  • Priority Order
  • Configuration Options
  • Custom Configuration
  • Error Handling
  • Security Best Practices
  • Example: Production Configuration
  • Example: Development Configuration

API Reference:

• API Reference
  • Overview
  • Clients
  • Core Components
  • Data Models
  • Enums
  • Configuration
  • CLI
  • Interfaces
• Client Documentation
  • AsyncClient
  • SyncClient
  • Authentication
  • Error Handling
• Data Models
  • Core Models
  • Plan Models
  • Supporting Models
  • Enums
  • Model Validation
  • Model Serialization

Guides:

• Usage Examples
  • Basic Examples
  • Advanced Examples
  • Data Processing Examples
  • CLI Integration Examples
  • Configuration Examples
  • Testing Examples
  • Performance Examples
• Command Line Interface
  • Installation
  • Basic Usage
  • Global Options
  • Command Reference
  • Configuration
  • Poetry Scripts
  • Makefile Commands
  • Output Formats
  • Error Handling
  • Exit Codes
  • Examples
• Authentication
  • How Authentication Works
  • Authentication Flow
  • Token Management
  • Accessing User Information
  • Authentication Errors
  • Token Expiration
  • Best Practices
  • Example: Secure Authentication
• Error Handling
  • Exception Types
  • Comprehensive Error Handling
  • Retry Logic
  • Rate Limiting
  • Error Logging
  • Custom Error Classes
  • Error Recovery Strategies
  • Best Practices
• Best Practices
  • Client Management
  • Concurrency
  • Pagination
  • Data Processing
  • Error Handling
  • Caching
  • Performance Optimization
  • Resource Management
  • Security
  • Code Organization
  • Testing
  • Documentation
  • Summary

Advanced Topics:

• Dynamic Pydantic Models
  • How It Works
  • Benefits
  • Model Generation Process
  • Example
  • Model Naming
  • Accessing Dynamic Models
  • Type Checking
  • Model Caching
  • Nested Structures
  • Validation
  • Serialization
  • Limitations
  • Workarounds
  • Best Practices
  • Example: Working with Dynamic Models
• Concurrency and Performance
  • Why Use Concurrency?
  • Basic Concurrency
  • Concurrent Pagination
  • Error Handling in Concurrent Operations
  • Rate Limiting
  • Batching Operations
  • Performance Tips
  • Example: Complete Concurrent Workflow
• Testing
  • Unit Testing
  • Integration Testing
  • Fixtures
  • Test Data
  • Best Practices
• Deployment
  • Production Considerations
  • Docker Deployment
  • Cloud Deployment
  • Monitoring
  • Performance Monitoring

Indices and tables

• Index

• Module Index

• Search Page