Client Documentation

The YouVersion Bible Client provides two main client implementations: synchronous and asynchronous.

AsyncClient

The AsyncClient is the primary client for modern Python applications using async/await patterns.

class AsyncClient(username=None, password=None)

Asynchronous client for YouVersion Bible API access.

Parameters:

• username – YouVersion username (optional if set in environment)

• password – YouVersion password (optional if set in environment)

async __aenter__()

Async context manager entry. Automatically authenticates the client.

async __aexit__(exc_type, exc_val, exc_tb)

Async context manager exit. Closes the HTTP client.

async moments(page=1)

Get user moments.

Parameters:

page – Page number to retrieve

Returns:

List of Moment objects

Return type:

List[Moment]

async highlights(page=1)

Get user highlights.

Parameters:

page – Page number to retrieve

Returns:

List of Highlight objects

Return type:

List[Highlight]

async verse_of_the_day(day=None)

Get verse of the day.

Parameters:

day – Specific day number (1-365), defaults to current day

Returns:

Votd object

Return type:

Votd

async notes(page=1)

Get user notes.

Parameters:

page – Page number to retrieve

Returns:

List of Note objects

Return type:

List[Note]

async bookmarks(page=1)

Get user bookmarks.

Parameters:

page – Page number to retrieve

Returns:

List of Moment objects

Return type:

List[Moment]

async my_images(page=1)

Get user images.

Parameters:

page – Page number to retrieve

Returns:

List of Image objects

Return type:

List[Image]

async plan_progress(page=1)

Get plan progress.

Parameters:

page – Page number to retrieve

Returns:

List of PlanSegmentCompletion objects

Return type:

List[PlanSegmentCompletion]

async plan_subscriptions(page=1)

Get plan subscriptions.

Parameters:

page – Page number to retrieve

Returns:

List of PlanSubscription objects

Return type:

List[PlanSubscription]

async convert_note_to_md()

Convert notes to markdown format.

Returns:

List of converted note data

Return type:

List[Dict[str, Any]]

async close()

Close the HTTP client.

Usage Example

import asyncio
from youversion import AsyncClient

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

        # Get highlights
        highlights = await client.highlights()
        for highlight in highlights[:5]:  # First 5 highlights
            print(f"Highlight: {highlight.moment_title}")

asyncio.run(main())

SyncClient

The SyncClient provides a synchronous wrapper around the AsyncClient for applications that prefer synchronous programming patterns.

class SyncClient(username=None, password=None)

Synchronous client for YouVersion Bible API access.

Parameters:

• username – YouVersion username (optional if set in environment)

• password – YouVersion password (optional if set in environment)

__enter__()

Context manager entry. Automatically authenticates the client.

__exit__(exc_type, exc_val, exc_tb)

Context manager exit. Closes the HTTP client.

moments(page=1)

Get user moments (synchronous).

Parameters:

page – Page number to retrieve

Returns:

List of Moment objects

Return type:

List[Moment]

highlights(page=1)

Get user highlights (synchronous).

Parameters:

page – Page number to retrieve

Returns:

List of Highlight objects

Return type:

List[Highlight]

verse_of_the_day(day=None)

Get verse of the day (synchronous).

Parameters:

day – Specific day number (1-365), defaults to current day

Returns:

Votd object

Return type:

Votd

notes(page=1)

Get user notes (synchronous).

Parameters:

page – Page number to retrieve

Returns:

List of Note objects

Return type:

List[Note]

bookmarks(page=1)

Get user bookmarks (synchronous).

Parameters:

page – Page number to retrieve

Returns:

List of Moment objects

Return type:

List[Moment]

my_images(page=1)

Get user images (synchronous).

Parameters:

page – Page number to retrieve

Returns:

List of Image objects

Return type:

List[Image]

plan_progress(page=1)

Get plan progress (synchronous).

Parameters:

page – Page number to retrieve

Returns:

List of PlanSegmentCompletion objects

Return type:

List[PlanSegmentCompletion]

plan_subscriptions(page=1)

Get plan subscriptions (synchronous).

Parameters:

page – Page number to retrieve

Returns:

List of PlanSubscription objects

Return type:

List[PlanSubscription]

convert_note_to_md()

Convert notes to markdown format (synchronous).

Returns:

List of converted note data

Return type:

List[Dict[str, Any]]

close()

Manually close the HTTP client.

Usage Example

from youversion import Client

with Client() as client:
    # Get verse of the day
    votd = client.verse_of_the_day()
    print(f"Today's verse: {votd.usfm}")

    # Get highlights
    highlights = client.highlights()
    for highlight in highlights[:5]:  # First 5 highlights
        print(f"Highlight: {highlight.moment_title}")

Authentication

Both clients support OAuth2 authentication using YouVersion’s authentication system. Credentials can be provided in several ways:

1. Environment Variables: Set YOUVERSION_USERNAME and YOUVERSION_PASSWORD

2. Constructor Parameters: Pass credentials directly to the client

3. Environment File: Create a .env file in your project root

# .env file
YOUVERSION_USERNAME=your_username
YOUVERSION_PASSWORD=your_password

Error Handling

Both clients raise appropriate exceptions for various error conditions:

• ValueError: Missing or invalid credentials

• httpx.HTTPStatusError: HTTP errors from the API

• RuntimeError: Invalid usage patterns (e.g., using SyncClient in async context)

from youversion import AsyncClient
import httpx

async def main():
    try:
        async with AsyncClient() as client:
            votd = await client.verse_of_the_day()
            print(f"Success: {votd.usfm}")
    except ValueError as e:
        print(f"Authentication error: {e}")
    except httpx.HTTPStatusError as e:
        print(f"API error: {e}")

asyncio.run(main())