Metadata-Version: 2.4
Name: nifty_anilist
Version: 0.1.1
Summary: Utilities for the Anilist GraphQL API.
Author-email: Alexey Polishchuk <alexpolishchukmail@gmail.com>
License: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: asyncio>=4.0.0
Requires-Dist: colorama>=0.4.6
Requires-Dist: gql[all]>=4.0.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: keyring>=25.6.0
Requires-Dist: pydantic>=2.11.9
Requires-Dist: pydantic-settings>=2.11.0
Requires-Dist: pyjwt>=2.10.1
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: selenium>=4.35.0
Requires-Dist: structlog>=25.4.0
Requires-Dist: webdriver-manager>=4.0.2
Dynamic: license-file

# Nifty Anilist Tools
 
## Overview

This is a simple utility library for interfacing with the [Anilist GraphQL API](https://docs.anilist.co/). It provides things like authentication and schema validation for requests.

### Setup

To use this library, you will need to have the variables shown in [.env.example](./.env.example) in environment variables or your local `.env` file.

## Features

### GraphQL Requests
The Anilist API is GraphQL-based and provides a [public schema](https://studio.apollographql.com/sandbox/schema/reference). This library uses [gql](https://github.com/graphql-python/gql) to make GraphQL requests. You should use the `anilist_request()` function in [request.py](./nifty_anilist/request.py) to make requests to Anilist.

### Anilist Auth

#### Token Storage
This library will store Anilist auth token(s) locally in one of two ways (customizable with the `TOKEN_SAVING_METHOD` environment variable):
1. Using your system's keyring (kept "permanently"): `KEYRING`
2. In-memory (lost when you restart your program): `IN_MEMORY`

#### Using Auth
In order to get an auth token for the first time, you can use the `sign_in_if_no_global()` function from [auth.py](./nifty_anilist/auth.py). After the first time, these details will be stored locally and added to your Anilist requests automatically.

**Note:** The sign-in function currently opens an instance of Google Chrome to the Anilist login page, from which your auth code will be automatically extracted. There will be more ways to do sign-in later.

There are two ways that auth headers can be added to your requests:
1. Using a global user ID stored in the `.env` file: The ID is stored as `ANILIST_CURRENT_USER`. This is the user ID that will be used to retrieve the token from the storage method(s) above. When making requests with `anilist_request()`, you can ignore the optional `user_id` parameter to use this approach. Example:
```py
async def do_something():
    request = gql("some query")
    anilist_request(request)

if __name__ == "__main__":
    sign_in_if_no_global()
    asyncio.run(do_something())
```
2. Manually passing in a user ID to the `anilist_request()` with the `user_id` parameter will try to get that user's token from local storage and use it instead of the global one. Example:
```py
async def do_something(user_id: str):
    request = gql("some query")
    anilist_request(request, user_id=user_id)

if __name__ == "__main__":
    my_user_id = "12345"
    asyncio.run(do_something(user_id=my_user_id))
```

You can also choose to not use auth on requests with the `use_auth` parameter (default is `True`):
```py
async def do_something():
    request = gql("some query")
    anilist_request(request, use_auth=False)
```
