Metadata-Version: 2.5
Name: py-openfigi2
Version: 0.2.0
Summary: OpenFIGI data source for Python
Project-URL: Homepage, https://github.com/romamo/py-openfigi
Project-URL: Repository, https://github.com/romamo/py-openfigi
Project-URL: Issues, https://github.com/romamo/py-openfigi/issues
Author-email: Roman Medvedev <pypi@romavm.dev>
License: MIT
License-File: LICENSE
Requires-Python: >=3.14
Requires-Dist: pydantic-market-data>=0.10.0
Requires-Dist: requests>=2.32.0
Requires-Dist: treaty<1.1,>=1.0.0rc12
Description-Content-Type: text/markdown

# py-openfigi

Python client for the [OpenFIGI API](https://www.openfigi.com/api) — map ISINs, tickers, CUSIPs and other identifiers to FIGI codes, and search or filter securities.

## Installation

Requires Python 3.14+.

```bash
pip install py-openfigi
```

## Usage

### Python API

```python
from openfigi import OpenFIGIDataSource, MappingJob, IdType

ds = OpenFIGIDataSource()  # set OPENFIGI_API_KEY env var for higher rate limits

# Resolve by ISIN
security = ds.resolve_query(isin="US0378331005")

# Bulk map identifiers
results = ds.map_identifiers([
    MappingJob(idType=IdType.ID_ISIN, idValue="US0378331005"),
    MappingJob(idType=IdType.TICKER, idValue="AAPL", exchCode="US"),
])

# Search by keyword
items = ds.search("Apple")
```

### CLI

```
openfigi lookup --isin US0378331005
openfigi lookup --symbol AAPL --exchange US --format json
openfigi lookup --desc "Apple" --limit 5
openfigi manifest    # every command, flag and exit code, for agents
```

The CLI is built on [treaty](https://github.com/romamo/treaty): output is a JSON envelope when stdout is not a terminal, and failures exit with a typed code:

| Exit | Code            | Meaning                                    |
|------|-----------------|--------------------------------------------|
| 2    | `ARG_ERROR`     | Invalid arguments; nothing was sent        |
| 5    | `NOT_FOUND`     | No security matches                        |
| 8    | `AUTH_REQUIRED` | `OPENFIGI_API_KEY` was rejected            |
| 10   | `TIMEOUT`       | OpenFIGI did not answer in time            |
| 11   | `RATE_LIMITED`  | Rate limit exceeded; retry after `error.retry_after_ms` |
| 12   | `UNAVAILABLE`   | OpenFIGI unreachable or returned HTTP 5xx  |

## Configuration

| Env var             | Description                                   |
|---------------------|-----------------------------------------------|
| `OPENFIGI_API_KEY`  | Optional API key for higher rate limits       |

## License

MIT
