Metadata-Version: 2.4
Name: podigeeconnector
Version: 0.4.1
Summary: Podigee Connector for Podcast Data
Author: Open Podcast
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4
Requires-Dist: loguru
Requires-Dist: pyyaml
Requires-Dist: requests
Requires-Dist: tenacity
Provides-Extra: docs
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: sphinx; extra == 'docs'
Requires-Dist: sphinx-autobuild; extra == 'docs'
Description-Content-Type: text/markdown

# Podigee Connector

[![Docs](https://readthedocs.org/projects/podigee-connector/badge?version=latest)](https://podigee-connector.readthedocs.io)

[![OpenPodcast Banner](https://raw.githubusercontent.com/openpodcast/banner/main/openpodcast-banner.png)](https://openpodcast.app/)

This is a simple library for connecting to the Podigee API.  
It can be used to export data from your dashboard at
https://app.podigee.com/analytics

## Supported Endpoints

- `/podcasts/{podcast_id}/analytics`
- `/podcasts/{podcast_id}/overview` (with optional scope parameter for totals)
- `/podcasts/{podcast_id}/analytics/episodes`
- `/episodes/{episode_id}/analytics`

See `__main__.py` for all endpoints.

## Credentials

This API supports three authentication methods:

1. Using the official API token. This option is preferred, but only available if you have a professional account.
2. Using Podigee username and password. Use this only if you don't have access to the API through your account.
3. Using a session cookie that you need to extract manually from your browser.

If possible, use option 1, the official API token, as it is the most secure and
officially supported authentication method.
Find more information on the different authentication methods below.

### Using the official API token

```python
from podigeeconnector import PodigeeConnector

connector = PodigeeConnector(
   base_url=BASE_URL,
   podigee_access_token=PODIGEE_ACCESS_TOKEN,
)
```

### Using the session token 

Alternatively, you can use a session token to log in:

```python
from podigeeconnector import PodigeeConnector

connector = PodigeeConnector(
   base_url=BASE_URL,
   podigee_session_v5=PODIGEE_SESSION_V5,
)
```

### Using username and password

Finally, you can also call the login endpoint with your username and password to log in:

```python
from podigeeconnector import PodigeeConnector

connector = PodigeeConnector.from_credentials(
   base_url=BASE_URL,
   podcast_id=PODCAST_ID,
   username=USERNAME,
   password=PASSWORD,
)
```

## Installation

```
pip install podigeeconnector
```

## Usage as a library

```python
from podigeeconnector import PodigeeConnector

connector = PodigeeConnector(
   base_url=BASE_URL,
   podigee_access_token=PODIGEE_ACCESS_TOKEN,
)

end = datetime.now()
start = end - timedelta(days=30)

podcast_analytics = connector.podcast_analytics(podcast_id, start, end)
logger.info("Podcast Analytics = {}", json.dumps(podcast_analytics, indent=4))

# Get totals with listeners and subscribers count
podcast_totals = connector.podcast_totals(podcast_id, start, end)
logger.info("Total Downloads: {}", podcast_totals.get("total_downloads"))
logger.info("Unique Listeners: {}", podcast_totals.get("unique_listeners_number"))

# Get total downloads for a specific episode
episode_total = connector.episode_total_downloads(episode_id, start, end)
logger.info("Episode Total Downloads: {}", episode_total)
```

See `__main__.py` for all endpoints.

## Development

We use [uv] for virtualenv and dependency management. With uv [installed][uv-install]:

1. Install your locally checked out code in editable mode, including all
   runtime, dev, and optional dependencies, into a project-local `.venv`:

```sh
uv sync --all-extras --dev
```

2. Create an environment file and fill in the required values:

```sh
cp .env.sample .env
```

3. Run the script (uv handles the virtualenv automatically):

```sh
uv run podigeeconnector
```

To add a new runtime dependency:

```sh
uv add $package
```

To add a new development-only dependency:

```sh
uv add --dev $package
```

To run linters, formatters, and tests:

```sh
make lint
make format-check
make test
```

## Releasing

1. Bump the `version` field in `pyproject.toml`.
2. Commit and tag the release (`git tag vX.Y.Z`), then push the tag.
3. Create a GitHub release for the tag. CI will build (`uv build`) and publish
   sdist + wheel to PyPI via `twine` using the `PYPI_API_TOKEN` secret.

To build and publish manually:

```sh
make publish
```

[uv]: https://docs.astral.sh/uv/
[uv-install]: https://docs.astral.sh/uv/getting-started/installation/