Client

Client#

PodMe API.

class podme_api.client.PodMeClient[source]#

Bases: object

A client for interacting with the PodMe API.

This class provides methods to authenticate, manage user data, and interact with podcasts and episodes through the PodMe service.

auth_client: PodMeAuthClient#

The authentication client.

Type:

auth_client (PodMeAuthClient)

disable_credentials_storage: bool = False#

Whether to disable credential storage.

language = 'no'#

The language setting for the client.

Type:

(PodMeLanguage)

region = 2#

The region setting for the client.

Type:

(PodMeRegion)

request_timeout: int = 15#

The timeout for API requests in seconds.

session: ClientSession | None = None#

The aiohttp.ClientSession to use for API requests.

Type:

(ClientSession | None)

set_conf_dir(conf_dir)[source]#

Set the configuration directory.

Parameters:

conf_dir (PathLike | str) – The path to the configuration directory.

Return type:

None

async save_credentials(filename=None)[source]#

Save the current authentication credentials to a file.

Parameters:

filename (PathLike | None) – The file to save the credentials to. If None, uses the default location.

Return type:

None

async load_credentials(filename=None)[source]#

Load authentication credentials from a file.

Parameters:

filename (PathLike | None) – The file to load the credentials from. If None, uses the default location.

Return type:

None

async static transcode_file(input_file, output_file=None, transcode_options=None)[source]#

Remux audio file using ffmpeg.

This will basically remux the audio file into another container format (version 1 of the MP4 Base Media format). Most likely this can be solved in better ways, but this will do for now. If the audio is served to clients in the original container (version 5 as of now), they will be very confused about the total duration of the file, for some reason…

Parameters:

  • input_file (PathLike | str) – The path to the audio file.

  • output_file (PathLike | str | None) – The path to the output file. By default, the output file will be the same as the input file with “_out” appended to the name.

  • transcode_options (dict[str, str] | None) – Additional transcode options.

Return type:

Path

async download_file(download_url, path, on_progress=None, on_finished=None, transcode=True)[source]#

Download a file from a given URL and save it to the specified path.

Parameters:

  • download_url (URL | str) – The URL of the file to download.

  • path (PathLike | str) – The local path where the file will be saved.

  • on_progress (Callable[[PodMeDownloadProgressTask, str, int, int], None], optional) – A callback function to report download progress. It should accept the download URL/path, current and total as arguments (current==total means 100%).

  • on_finished (Callable[[str, str], None], optional) – A callback function to be called when the download is complete. It should accept the download URL and save path as arguments.

  • transcode (bool, optional) – Whether to transcode the file. Defaults to True.

Raises:

PodMeApiDownloadError – If there’s an error during the download process.

Return type:

None

async download_files(download_info, on_progress=None, on_finished=None)[source]#

Download multiple files concurrently.

Parameters:

  • download_info (list[tuple[URL | str, Path | str]]) – A list of tuples containing the download URL and save path for each file.

  • on_progress (Callable[[PodMeDownloadProgressTask, str, int, int], None], optional) – A callback function to report download progress. It should accept the download URL/path, current and total as arguments (current==total means 100%).

  • on_finished (Callable[[str, str], None], optional) – A callback function to be called when the download is complete. It should accept the download URL and save path as arguments.

async get_episode_download_url(episode)[source]#

Get the download URL for an episode.

Parameters:

episode (PodMeEpisode | int) – The episode object or episode ID to get the download URL for.

Returns:

The episode ID and the download URL.

Return type:

tuple[int, URL]

Raises:

PodMeApiStreamUrlError – If unable to find url from m3u8, or if the url isn’t downloadable.

async get_episode_download_url_bulk(episodes)[source]#

Get download URLs for a list of episodes.

This method fetches download URLs for multiple episodes concurrently and ensures that only unique episode IDs are included in the result.

Parameters:

episodes (list[PodMeEpisode | int]) – A list of PodMeEpisode objects or episode IDs for which to fetch download URLs.

Returns:

A list of tuples, each containing an episode ID and its corresponding download URL. Duplicate episode IDs are removed.

Return type:

list[tuple[int, URL]]

Raises:

PodMeApiStreamUrlError – If unable to find url from m3u8, or if the url isn’t downloadable.

async get_username()[source]#

Get the username of the authenticated user.

Return type:

str

async get_user_subscription()[source]#

Get the user’s subscriptions.

Return type:

list[PodMeSubscription]

async get_user_podcasts()[source]#

Get the user’s podcasts.

Return type:

list[PodMePodcast]

async get_categories(region=None)[source]#

Get podcast categories for a specific region.

Parameters:

region (PodMeRegion | None) – The region to get categories for. If None, uses the client’s default region.

Return type:

list[PodMeCategory]

async get_category(category_id, region=None)[source]#

Get a category by its ID or key.

Parameters:

  • category_id (int | str) – The ID or key of the category.

  • region (PodMeRegion, optional) – The region to get the category for. If None, uses the client’s default region.

Return type:

PodMeCategory

async get_category_by_id(category_id, region=None)[source]#

Get a category by its ID.

Parameters:

  • category_id (int) – The ID of the category.

  • region (PodMeRegion, optional) – The region to get the category for. If None, uses the client’s default region.

Return type:

PodMeCategory

async get_category_by_key(category_key, region=None)[source]#

Get a category by its key.

Parameters:

  • category_key (str) – The key of the category.

  • region (PodMeRegion, optional) – The region to get the category for. If None, uses the client’s default region.

Return type:

PodMeCategory

async get_category_page(category, region=None)[source]#

Get the page for a specific category.

Parameters:

  • category (PodMeCategory | int | str) – The category, its ID, or its key.

  • region (PodMeRegion, optional) – The region to get the category page for. If None, uses the client’s default region.

Return type:

PodMeCategoryPage

async get_podcasts_by_category(category, region=None, pages=None, page_size=None)[source]#

Get podcasts for a specific category.

Parameters:

  • category (PodMeCategory | int) – The category or its ID.

  • region (PodMeRegion, optional) – The region to get podcasts for. If None, uses the client’s default region.

  • pages (int, optional) – The number of pages to retrieve.

  • page_size (int, optional) – The number of items per page.

Return type:

list[PodMePodcastBase]

async get_home_screen()[source]#

Get the home screen content.

Return type:

PodMeHomeScreen

Get popular podcasts.

Parameters:

  • podcast_type (int, optional) – The type of podcasts to retrieve.

  • category (PodMeCategory | str, optional) – The category or category key to filter by.

  • pages (int, optional) – The number of pages to retrieve.

  • page_size (int, optional) – The number of items per page.

Return type:

list[PodMePodcastBase]

async is_subscribed_to_podcast(podcast_id)[source]#

Check if the user is subscribed to a podcast.

Parameters:

podcast_id (int) – The ID of the podcast.

Return type:

bool

async subscribe_to_podcast(podcast_id)[source]#

Subscribe to a podcast.

Parameters:

podcast_id (int) – The ID of the podcast to subscribe to.

Return type:

bool

async unsubscribe_to_podcast(podcast_id)[source]#

Unsubscribe from a podcast.

Parameters:

podcast_id (int) – The ID of the podcast to unsubscribe from.

Return type:

bool

async scrobble_episode(episode_id, playback_progress=None, has_completed=False)[source]#

Update the playback progress for an episode.

Parameters:

  • episode_id (int) – The ID of the episode.

  • playback_progress (time | str, optional) – The current playback position.

  • has_completed (bool, optional) – Whether the episode has been completed. Defaults to False.

Return type:

bool

async get_currently_playing()[source]#

Get the list of currently playing episodes.

Return type:

list[PodMeEpisode]

async get_podcast_info(podcast_slug)[source]#

Get information about a podcast.

Parameters:

podcast_slug (str) – The slug of the podcast.

Return type:

PodMePodcast

async get_podcasts_info(podcast_slugs)[source]#

Get information about multiple podcasts.

Parameters:

podcast_slugs (list[str]) – The slugs of the podcasts.

Return type:

list[PodMePodcast]

async get_episode_info(episode_id)[source]#

Get information about an episode.

Parameters:

episode_id (int) – The ID of the episode.

Return type:

PodMeEpisode

async get_episodes_info(episode_ids)[source]#

Get information about multiple episodes.

Parameters:

episode_ids (list[int]) – The IDs of the episodes.

Return type:

list[PodMeEpisode]

async search_podcast(search, pages=None, page_size=None)[source]#

Search for podcasts.

Parameters:

  • search (str) – The search query.

  • pages (int, optional) – The number of pages to retrieve.

  • page_size (int, optional) – The number of items per page.

Return type:

list[PodMeSearchResult]

async get_episode_list(podcast_slug)[source]#

Get the full list of episodes for a podcast.

Parameters:

podcast_slug (str) – The slug of the podcast.

Return type:

list[PodMeEpisode]

async get_latest_episodes(podcast_slug, episodes_limit=20)[source]#

Get the latest episodes for a podcast.

Parameters:

  • podcast_slug (str) – The slug of the podcast.

  • episodes_limit (int, optional) – The maximum number of episodes to retrieve. Defaults to 20.

Return type:

list[PodMeEpisode]

async get_episode_ids(podcast_slug)[source]#

Get the IDs of all episodes for a podcast.

Parameters:

podcast_slug – The slug of the podcast.

Return type:

list[int]

async check_stream_url(stream_url)[source]#

Check if a stream URL is downloadable.

Parameters:

stream_url (URL | str) – The URL to check.

Return type:

FetchedFileInfo

Returns:

The content length and content type if the URL is downloadable, None otherwise.

async resolve_stream_url(stream_url)[source]#

Check if a stream URL is downloadable.

Parameters:

stream_url (URL | str) – The URL to check.

Return type:

FetchedFileInfo

Returns:

The content length and content type if the URL is downloadable, None otherwise.

Raises:

PodMeApiStreamUrlError – If unable to find url from m3u8, or if the url isn’t downloadable.

async close()[source]#

Close open client session.

Return type:

None

Contents