Skip to content

plan.md

Latest commit

 

History

History
90 lines (70 loc) · 4.51 KB

plan.md

File metadata and controls

90 lines (70 loc) · 4.51 KB

Plan: Implement User Login API Function

This plan outlines the first step in building the Pocket Casts Python API library: implementing the POST /user/login_pocket_casts endpoint. The goal is to create a robust, testable, and well-documented login feature, establishing patterns for future API functions.

Steps

  1. Define User Data Model

    • Add a User model in api_pocketcasts/models/user.py based on data-model.md.
    • Update api_pocketcasts/models/__init__.py to import the new model.

  2. Implement Login API Method

    • Add a login_pocket_casts(email, password) method to api_pocketcasts/client.py.
    • Use httpx for the HTTP request, parse response into the User model.
    • Handle errors using custom exceptions from exceptions.py.

  3. Add Authentication Logic

    • Place authentication helpers in api_pocketcasts/auth.py if needed.
    • Ensure credentials/tokens are only held in memory.

  4. Write Unit and Integration Tests

    • Create tests/login_test.py to cover successful login, invalid credentials, and error handling.
    • Use environment variables for test credentials.

  5. Document the Login Feature

    • Update docs/usage.md with login usage examples and expected responses.
    • Add docstrings to all new functions and models.
      • Function Docstrings: Every test function must have a concise docstring explaining the scenario being tested, what is simulated, and the expected outcome.

  6. Update pyproject.toml

    • Ensure dependencies (httpx, attrs, pytest) are listed.
    • Set project metadata if not already present.

  7. Linting and CI

    • Confirm code style with linters (e.g., flake8, black if used).
    • Ensure GitHub Actions runs tests and lint checks.

Further Considerations

  1. Should the login method be synchronous, asynchronous, or both? (Recommend both for consistency.)
  2. Should error messages be standardized across all API methods?
  3. Confirm if additional login flows (Google, Sonos) are needed in the future.

Plan: Implement User Podcast Subscription Management

This plan expands the Pocket Casts Python API library to fully support user podcast subscriptions, including retrieving, adding, and removing subscriptions via the following endpoints:

  • POST /user/podcast/list: Retrieve the user's subscribed podcasts.
  • POST /user/podcast/subscribe: Add a podcast to the user's subscriptions.
  • POST /user/podcast/unsubscribe: Remove a podcast from the user's subscriptions.

Steps

  1. Define Podcast and Subscription Data Models

    • Add or update Podcast and any supporting models in api_pocketcasts/models/podcast.py based on data-model.md and API responses.
    • Add a PodcastList or similar container model if the response is a list.
    • Add a SubscriptionResult or similar model for subscribe/unsubscribe responses if needed.
    • Update api_pocketcasts/models/__init__.py to import the new model(s).

  2. Implement Subscription API Methods

    • Add the following methods to api_pocketcasts/client.py (and async_client.py):
      • get_subscribed_podcasts()
      • subscribe_to_podcast(podcast_id)
      • unsubscribe_from_podcast(podcast_id)
    • Use httpx for HTTP requests, parse responses into the new model(s).
    • Handle errors using custom exceptions from exceptions.py.

  3. Add Authentication Logic (if needed)

    • Ensure all methods use the current access token and handle token refresh if required.

  4. Write Unit and Integration Tests

    • Create or update tests (e.g., tests/podcast_list_test.py, tests/podcast_subscribe_test.py) to cover:
      • Successful retrieval, subscription, and unsubscription
      • Edge cases (already subscribed, not found, already unsubscribed, etc.)
      • Error handling
    • Use environment variables for test credentials.

  5. Document the Subscription Features

    • Update docs/usage.md with usage examples and expected responses for all new methods.
    • Add docstrings to all new functions and models.

  6. Update pyproject.toml (if needed)

    • Ensure any new dependencies are listed.

  7. Linting and CI

    • Confirm code style with linters (e.g., flake8, black).
    • Ensure GitHub Actions runs tests and lint checks.

Further Considerations

  1. Should the methods support pagination or filtering if the API allows?
  2. Should all methods be available in both sync and async clients?
  3. Confirm if additional podcast list endpoints (e.g., archived, starred) are needed in the future.
  4. Consider idempotency and error handling for repeated subscribe/unsubscribe calls.