Readeck Python Client

A Python client library for the Readeck API, providing easy access to Readeck's bookmark and reading features.

Features

• Full async/await support
• Type hints with Pydantic models
• Comprehensive error handling
• Support for Python 3.10+
• Easy authentication with Bearer tokens

Installation

pip install readeck

Quick Start

import asyncio
from readeck import ReadeckClient

async def main():
    client = ReadeckClient(
        base_url="https://your-readeck-instance.com",
        token="your-bearer-token"
    )

    # Get user profile
    profile = await client.get_user_profile()
    print(f"Welcome, {profile.user.username}!")

    # Create a bookmark
    result = await client.create_bookmark(
        url="https://example.com/article",
        title="Interesting Article",
        labels=["reading", "tech"]
    )
    print(f"Bookmark created with ID: {result.bookmark_id}")

    await client.close()

if __name__ == "__main__":
    asyncio.run(main())

Authentication

The client uses Bearer token authentication. You can obtain your token from your Readeck instance's settings.

client = ReadeckClient(
    base_url="https://your-readeck-instance.com",
    token="your-bearer-token"
)

API Reference

User Profile

Get the current user's profile information:

profile = await client.get_user_profile()

Returns a UserProfile object containing:

• User information (username, email, creation date)
• Authentication provider details
• User settings and preferences
• Reader settings (font, font size, line height)

Bookmarks

Create Bookmark

Create a new bookmark:

# Minimal bookmark
result = await client.create_bookmark(url="https://example.com")

# Bookmark with title
result = await client.create_bookmark(
    url="https://example.com/article",
    title="Article Title"
)

# Bookmark with labels
result = await client.create_bookmark(
    url="https://example.com/tutorial",
    labels=["tutorial", "programming"]
)

# Complete bookmark
result = await client.create_bookmark(
    url="https://example.com/complete",
    title="Complete Example",
    labels=["example", "complete", "demo"]
)

The create_bookmark method returns a BookmarkCreateResult object containing:

• response: The API response with message and status
• bookmark_id: The ID of the created bookmark (from response headers)
• location: The URL of the created resource (from response headers)

Get Bookmarks

Retrieve bookmarks with optional filtering:

# Get all bookmarks
bookmarks = await client.get_bookmarks()

# Get bookmarks with parameters
from readeck import BookmarkListParams

params = BookmarkListParams(
    limit=10,
    search="python",
    labels="programming"
)
bookmarks = await client.get_bookmarks(params)

Export Bookmarks

Export bookmarks in different formats:

bookmark_id = "some_bookmark_id"

# Export as markdown (default format)
markdown_content = await client.export_bookmark(bookmark_id)

# Export as markdown explicitly
markdown_content = await client.export_bookmark(bookmark_id, format="md")

# Export as EPUB
epub_content = await client.export_bookmark(bookmark_id, format="epub")

# Save to files
with open("article.md", "w", encoding="utf-8") as f:
    f.write(markdown_content)

with open("article.epub", "wb") as f:
    f.write(epub_content)

Supported export formats:

• md (markdown) - Returns a string with the article content as markdown
• epub - Returns bytes containing the EPUB file data

Development

This project uses uv for dependency management:

# Install dependencies
uv sync --dev

# Run tests
uv run pytest

# Run integration tests (requires Docker)
uv run pytest tests/integration

# Run linting and formatting
uv run ruff check src tests --fix
uv run ruff format src tests
uv run mypy src

# Run all checks
uv run pre-commit run --all-files

License

MIT License. See LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.