Metadata-Version: 2.4
Name: nexus-mods-api
Version: 1.0.0
Summary: Typed sync and async Python clients for the Nexus Mods APIs
Project-URL: Homepage, https://github.com/Modding-Forge/nexus-mods-api-py
Project-URL: Documentation, https://github.com/Modding-Forge/nexus-mods-api-py/tree/master/docs
Project-URL: Repository, https://github.com/Modding-Forge/nexus-mods-api-py
Project-URL: Issues, https://github.com/Modding-Forge/nexus-mods-api-py/issues
Project-URL: Changelog, https://github.com/Modding-Forge/nexus-mods-api-py/blob/master/docs/modules/development/pages/changelog.adoc
Author-email: Modding Forge <info@moddingforge.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api-client,asyncio,nexus-mods,oauth2,pydantic
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.28.1
Requires-Dist: pydantic<3,>=2.11
Provides-Extra: all
Requires-Dist: websockets<17,>=15; extra == 'all'
Provides-Extra: sso
Requires-Dist: websockets<17,>=15; extra == 'sso'
Description-Content-Type: text/markdown

# nexus-mods-api

[![PyPI - Version](https://img.shields.io/pypi/v/nexus-mods-api)](https://pypi.org/project/nexus-mods-api/)
[![Python](https://img.shields.io/pypi/pyversions/nexus-mods-api)](https://pypi.org/project/nexus-mods-api/)
[![License](https://img.shields.io/pypi/l/nexus-mods-api)](LICENSE)
[![CI](https://github.com/Modding-Forge/nexus-mods-api-py/actions/workflows/ci.yml/badge.svg)](https://github.com/Modding-Forge/nexus-mods-api-py/actions/workflows/ci.yml)

Unofficial, typed synchronous and asynchronous Python clients for all three
Nexus Mods APIs:

- REST v1 with hand-written Pydantic v2 models
- GraphQL v2 with typed execution and convenience queries
- REST v3 generated from a checked-in, SHA-256-pinned OpenAPI specification

Authentication supports manual application-specific API keys, WebSocket SSO,
and OAuth 2.0 Authorization Code with PKCE. OAuth applications do not use a
client secret.

## Installation

```console
python -m pip install nexus-mods-api
```

Python 3.12 or newer is required. Install the optional WebSocket dependency for
SSO:

```console
python -m pip install "nexus-mods-api[sso]"
```

## Quick start

```python
from nexusmods_api import ApiKeyAuth, NexusClient, NexusConfig

config = NexusConfig(
    application_name="your-registered-app",
    application_version="1.0.0",
)

with NexusClient(config, ApiKeyAuth.from_value("your-api-key")) as client:
    games = client.v1.get_games()
```

Equivalent native async clients are available for applications that already
use an event loop. The aggregate clients lazily construct their REST v1,
GraphQL v2, and REST v3 clients.

## Documentation

The authoritative documentation is maintained as AsciiDoc, starting at the
[documentation overview](docs/modules/ROOT/pages/index.adoc). It includes
installation, sync and async usage, all authentication flows, API guides,
error handling, rate limits, code generation, testing, and releases.

Version `1.0.0` completed both the mocked conformance suite and live acceptance
tests for manual API key, SSO, and OAuth with maintainer-owned Nexus Mods
application registrations.

## License

MIT — see [LICENSE](LICENSE).

## About Modding Forge

`nexus-mods-api` is built for the Python tooling behind
[Modding Forge](https://moddingforge.com).

This project is not affiliated with or endorsed by Nexus Mods.
