Metadata-Version: 2.4
Name: aperiodic-factors
Version: 0.1.1
Summary: Client for the Aperiodic Factors API (factors.aperiodic.io): cross-sectional crypto factors, portfolios and risk signals
Project-URL: Issues, https://github.com/aperiodic-io/client-factors/issues
Project-URL: Source, https://github.com/aperiodic-io/client-factors
Author: Aperiodic Factors
License-Expression: MIT
License-File: LICENSE
Keywords: api,backtesting,factors,market-neutral,portfolio,quant,risk
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
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: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.9
Requires-Dist: numpy>=1.3.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: requests>=2.25.0
Provides-Extra: quality
Requires-Dist: pre-commit~=2.20.0; extra == 'quality'
Requires-Dist: ruff==0.1.11; extra == 'quality'
Provides-Extra: tests
Requires-Dist: hypothesis~=6.112.4; extra == 'tests'
Requires-Dist: pytest-cov>=4.0; extra == 'tests'
Requires-Dist: pytest~=7.1.2; extra == 'tests'
Requires-Dist: python-dotenv>=1.0.0; extra == 'tests'
Description-Content-Type: text/markdown

# Aperiodic Factors Client

A Python client library for the [Aperiodic Factors](https://factors.aperiodic.io)
API, providing convenient wrappers for cross-sectional crypto factor data,
portfolio weights/returns and risk signals.

## Installation

```bash
pip install aperiodic-factors
```

## Features

- **Portfolio Data**: Access historical and live portfolio weights
- **Cross-section Factors**: Access cross-sectional factors as raw data
- **Risk Signals**: Retrieve normalized risk factor series for cryptocurrencies
- **Easy Integration**: Simple API calls with pandas DataFrame/Series returns

## Quick Start

```python
import aperiodic_factors

# Set your API key
api_key = "your-api-key-here"

# Get historical portfolio weights
historical_weights = aperiodic_factors.get_portfolio_historical_weights(
    id="your-portfolio-id",
    api_key=api_key,
    start_date="2024-01-01",
    end_date="2024-12-31",
)

# Get current portfolio weights
live_weights = aperiodic_factors.get_live_weights(
    id="your-portfolio-id",
    api_key=api_key,
)

# Get portfolio returns
returns = aperiodic_factors.get_portfolio_returns(
    id="your-portfolio-id",
    api_key=api_key,
    start_date="2024-01-01",
)

# Get portfolio tickers
tickers = aperiodic_factors.get_tickers(
    id="momentum",  # Portfolio factor identifier without universe specifier
    api_key=api_key,
    universe_size="full",
)

# Get historical factors
factors = aperiodic_factors.get_portfolio_factors_historical(
    id="momentum",
    tickers=["BTC", "ETH"],
    api_key=api_key,
)

# Get live factors (latest factor data)
live_factors = aperiodic_factors.get_portfolio_factors_live(
    id="momentum",
    tickers=["BTC", "ETH"],
    api_key=api_key,
)

# Get historical universe
universe = aperiodic_factors.get_historical_universe(
    size="full",
    start_date="2024-01-01",
    end_date="2024-12-31",
    api_key=api_key,
)
```

## Configuration

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `APERIODIC_API_KEY` | yes | — | Your Aperiodic Factors API key |
| `APERIODIC_BASE_URL` | no | `https://factors.aperiodic.io` | Override the API base URL |
| `CF_ACCESS_CLIENT_ID` | no | — | Cloudflare Access service-token id (protected environments) |
| `CF_ACCESS_CLIENT_SECRET` | no | — | Cloudflare Access service-token secret |

## Requirements

- Python 3.9+
- pandas >= 2.0.0
- numpy >= 1.3.0
- requests >= 2.25.0

## Testing

The test suite exercises the live API, so it needs a valid API key. Tests that
require it are skipped automatically when `APERIODIC_API_KEY` is not set.

```bash
# Install with test dependencies
pip install -e ".[tests]"

# Run all tests
export APERIODIC_API_KEY="your_api_key_here"
pytest tests/ -v
```

## License

MIT License
