Skip to content

PRODUCT.md

Latest commit

 

History

History
138 lines (94 loc) · 5.93 KB

PRODUCT.md

File metadata and controls

138 lines (94 loc) · 5.93 KB

PRODUCT.md

Product Overview

Pocket Casts Python Client is a modern, developer-focused library enabling direct, efficient programmatic access to the Pocket Casts podcast service via its unofficial API. The library is designed for Python 3.x and targets applications, scripts, and integrations where automated or custom podcast workflows, data retrieval, and user management are desired.

This package is not a standalone application—it offers no user-facing frontend. Instead, it exposes a robust interface for Python developers, allowing them to interact with Pocket Casts features from within their own code.

Key Features

1. Authentication & User Management

  • Email/Password Login: Authenticate Pocket Casts users with email and password using secure token-based flows.
  • Session Management: Handles token refreshing; maintains secure access tokens for authenticated sessions.
  • Logout: Clean removal of credentials and tokens from session.

2. Podcast & Episode Management

  • Get Subscribed Podcasts: Retrieve the authenticated user’s subscriptions with full metadata.
  • Get Podcast Details: Fetch comprehensive data for any podcast, including all episodes, show notes, and artwork URLs.
  • Get Episodes: List all episodes for a given podcast, with playback and metadata details.
  • Search: Powerful podcast and episode search with filtering.

3. Subscription & Playback Control

  • Subscribe/Unsubscribe: Add or remove podcasts from the user’s subscription list.
  • Sync Playback Status: Track episode progress (position, played/unplayed status).
  • Archive/Unarchive: Manage episode archival state automatically based on user actions.

4. Bookmarks & Playlists

  • Bookmarks: Add, view, or delete time-stamped bookmarks within episodes.
  • Playlists/Filters: Fetch and use Pocket Casts’ filter system to organize episodes client-side.

5. Listening History & Stats

  • History Sync: Add episodes to listening history; remove individually or clear all.
  • Playback Statistics: Sync time listened, silence-skipped, and playback enhancements; view cumulative stats.

6. Discovery

  • Top Charts, Featured, Trending Podcasts: Access curated cross-platform recommendations.
  • Personalized Recommendations: Retrieve podcasts recommended based on user’s listening habits.
  • Similar & Social Recommendations: Find new content based on subscriptions or communities.

7. Show Notes & Chapters

  • Show Notes: Access rich HTML show notes for podcasts and episodes.
  • Chapters: Fetch Podcast Index format chapters for episode navigation.

8. Up Next Queue Control

  • Queue Manipulation: Add, remove, and reorder episodes in the user’s “Up Next” queue for playback continuity.

Architecture Highlights

  • Sync API Only: Only synchronous (PocketCastsClient) Python usage is currently supported. Async support may be added in the future.
  • Modern Patterns: Utilizes httpx for HTTP requests, attrs for data models, and type hints for clarity.
  • Stateless Design: No persistent local storage; all data is fetched from Pocket Casts servers on-demand, keeping library lightweight.
  • Extensible Data Model: Podcast, episode, and related objects are conveniently mapped and can be extended by client applications.
  • Image & Artwork Management: Auto-generates Pocket Casts artwork URLs in multiple sizes from known patterns.

Supported Environments

  • Python 3.7+
  • Works on Linux, macOS, Windows
  • Requires: httpx, attrs, pytest, and standard Python ecosystem

Planned Extensions

  • Future releases may add:
    • Automated local caching
    • Richer management of bookmarks/filters
    • Support for additional unofficial endpoints as discovered
    • Asynchronous API support
    • Improved error handling and contract validation

Limitations

  • Unofficial API: May break if Pocket Casts alters its public/internal API.
  • No UI: This package provides programmatic access only; building user-facing experiences is left to consumers.
  • No local persistence: Consumers are responsible for all local data management.
  • Credentials Management: Applications must handle their own secure credential storage and handling.
  • Only synchronous API is available.
  • Some endpoints/features are not yet implemented. See below.

Pending Features & Endpoints

The following endpoints/features are planned but not yet implemented in the library:

  • Bookmarks: Add/view/delete time-stamped bookmarks within episodes
  • Playlists/Filters: Fetch and use Pocket Casts’ filter system to organize episodes client-side
  • Listening History & Stats: Add episodes to listening history, sync playback statistics
  • Recommendations: Top charts, featured, trending, personalized, social recommendations
  • Show Notes & Chapters: Access rich HTML show notes and chapters for podcasts/episodes

Planned endpoints (see README.md for full list):

  • 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 would like to contribute to these features, see CONTRIBUTING.md and open an issue or pull request.

Who Should Use This Library?

  • Developers building custom podcast clients, data sync tools, or analytic platforms.
  • Researchers seeking large-scale access to podcasts/episodes for data analysis.
  • Power users integrating Pocket Casts with personal dashboards, automation tools, or workflow engines.

Getting Started

See README.md for API documentation and installation instructions.
Community contributions and issues are welcome!