Metadata-Version: 2.4
Name: esporifai
Version: 0.3.0
Summary: A modern CLI for collecting Spotify listening data.
Author: Sergio Sánchez Zavala
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/chekos/esporifai
Project-URL: Issues, https://github.com/chekos/esporifai/issues
Project-URL: CI, https://github.com/chekos/esporifai/actions
Project-URL: Changelog, https://github.com/chekos/esporifai/releases
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<0.29,>=0.28
Requires-Dist: playwright>=1.58.0
Requires-Dist: python-dotenv<2.0,>=1.0
Requires-Dist: rich<14.0,>=13.9
Requires-Dist: typer<1.0,>=0.16
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-dotenv>=0.5.2; extra == "test"
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-dotenv>=0.5.2; extra == "dev"
Requires-Dist: ruff>=0.11.0; extra == "dev"
Requires-Dist: twine>=6.1.0; extra == "dev"
Dynamic: license-file

# esporifai

[![PyPI](https://img.shields.io/pypi/v/esporifai.svg)](https://pypi.org/project/esporifai/)
[![Changelog](https://img.shields.io/github/v/release/chekos/esporifai?include_prereleases&label=changelog)](https://github.com/chekos/esporifai/releases)
[![Tests](https://github.com/chekos/esporifai/workflows/Test/badge.svg)](https://github.com/chekos/esporifai/actions?query=workflow%3ATest)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/chekos/esporifai/blob/master/LICENSE)

A modern CLI for collecting Spotify listening data from the Spotify Web API.

## Installation

Install this tool using `pip`:

    pip install esporifai

For development:

    python -m pip install -e '.[dev]'

## Usage

For help, run:

    esporifai --help

You can also use:

    python -m esporifai --help

### Recently played tracks
To retrieve recently played tracks, run:

    esporifai get-recently-played

For help,

    esporifai get-recently-played --help

### Authentication

`esporifai` uses Spotify authorization code flow and stores auth artifacts in your app config directory.

Required environment variables:

    SPOTIFY_CLIENT_ID=...
    SPOTIFY_AUTH_STRING=...
    REDIRECT_URI=...
    USERNAME=...  # or SPOTIFY_USERNAME
    PASSWORD=...  # or SPOTIFY_PASSWORD

For stable automation, prefer a long-lived refresh token:

    SPOTIFY_REFRESH_TOKEN=...

Useful auth commands:

    esporifai auth --check
    esporifai auth --status
    esporifai auth --url
    esporifai auth --code <authorization-code>
    esporifai auth --force

`esporifai` will use auth in this order:

    1. cached access token
    2. cached refresh token
    3. SPOTIFY_REFRESH_TOKEN from the environment
    4. browser login flow

Optional runtime tuning:

    ESPORIFAI_REQUEST_TIMEOUT_SECONDS=30
    ESPORIFAI_BROWSER_SLOW_MO_MS=300
    ESPORIFAI_LOGIN_TIMEOUT_MS=30000
    ESPORIFAI_CONSENT_TIMEOUT_MS=5000
    ESPORIFAI_REDIRECT_TIMEOUT_MS=90000

## Development

To contribute to this tool, first checkout the code. Then create a new virtual environment:

    cd esporifai
    python -m venv venv
    source venv/bin/activate

Now install the dependencies and test dependencies:

    python -m pip install -e '.[dev]'

To run the tests:

    python -m pytest -m "not integration"

To run the live Spotify integration tests:

    python -m pytest -m integration
