Pocket Casts Python API Client

A robust, fully tested, and well-documented Python client for the Pocket Casts API. Supports synchronous usage, secure in-memory authentication, and a standardized error handling model.

Features

• Synchronous API client
• Secure authentication (tokens/credentials only in memory)
• Standardized error structure (code, message, details)
• Extensible data models using attrs
• Full unit and integration test coverage
• Python 3.7+ support
• No persistent storage or database layer

Data Models

All data models are defined using the attrs library for consistency and reliability. For details and examples, see API Reference and data-model.md.

Installation

Clone the repository and install in editable mode:

git clone https://github.com/yfhyou/api_pocketcasts.git
cd api_pocketcasts
pip install -e .

Dependencies are managed in pyproject.toml.

Usage

from api_pocketcasts.client import PocketCastsClient
client = PocketCastsClient()
user = client.login_pocket_casts("your@email.com", "yourpassword")
print(user.email, user.access_token)

See Usage Guide for more examples and error handling.

Error Handling

All API errors use a standardized structure:

• code: Short error code (e.g., auth_error)
• message: Human-readable error message
• details: Additional error context (dict)

Example:

from api_pocketcasts.exceptions import PocketCastsAuthError
try:
	user = client.login_pocket_casts("bad@example.com", "wrong")
except PocketCastsAuthError as e:
	print(f"Error code: {e.code}")
	print(f"Message: {e.message}")
	print(f"Details: {e.details}")

See docs/usage.md for details.

Documentation

• Usage Guide
• API Reference
• Endpoints
• Feature Plan

Testing & Test Documentation Standards

All tests are written using pytest and follow these documentation standards:

• Module-Level Docstring: Each test file should begin with a docstring describing the overall purpose of the test suite, what is covered, and any setup/teardown requirements.
• Function Docstrings: Every test function must have a concise docstring explaining the scenario being tested, what is simulated, and the expected outcome.
• Descriptive Test Names: Test function names should clearly state what is being tested and under what condition (e.g., test_login_generic_http_error).
• pytest Markers: Use markers like @pytest.mark.unit or @pytest.mark.integration to categorize tests.
• No Redundant Comments: Avoid comments that simply restate the function name or docstring.

Example:

"""
Unit tests for Pocket Casts API authentication and token refresh logic.

This test suite covers error handling, edge cases, and expected behaviors for:
- User login (including HTTP errors, malformed responses, timeouts, and invalid credentials)
- Token refresh (success, malformed response, unexpected errors, and empty tokens)
"""

@pytest.mark.unit
def test_login_generic_http_error(monkeypatch):
	"""
	Simulate a generic HTTP 500 error during login.
	Ensures PocketCastsAuthError is raised when the API returns a server error.
	"""
	# ...test code...

This approach ensures tests are self-explanatory, maintainable, and easy for contributors to understand.

Unfinished & Pending Endpoints

The following API endpoints are not yet implemented in this library. They are planned for future releases, but currently do not work and are not available to end users:

• POST /user/bookmark/list
• POST /user/bookmark/add
• POST /user/bookmark/delete
• POST /user/podcast/episode/bookmarks
• POST /user/podcast/episodes/bookmarks
• POST /user/stats/add
• POST /sync/update_episode
• POST /sync/update_episode_star
• POST /sync/update_episodes_archive
• POST /history/do
• POST /discover/recommend_episodes
• GET /recommendations/podcast/{podcast_uuid}
• GET /recommendations/social
• GET /recommendations/user_podcast

If you need support for these endpoints, please open an issue or contribute a PR. See reference/endpoints.md for the full list and status.

Contributing

See CONTRIBUTING.md for guidelines on contributing, coding standards, and submitting issues or pull requests.

License

See LICENSE for license information.