Metadata-Version: 2.4
Name: playerdatapy
Version: 1.8.1
Summary: Python client for the PlayerData GraphQL API
Author-email: PlayerData Engineering <dev@playerdata.com>
License-File: LICENSE
Requires-Python: <3.14,>=3.10
Requires-Dist: graphql-core>=3.2.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: oauthlib>=3.2.0
Requires-Dist: polars>=1.37.1
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests-oauthlib>=2.0.0
Provides-Extra: dev
Requires-Dist: ariadne-codegen>=0.17.0; extra == 'dev'
Requires-Dist: ipykernel>=7.1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.4.2; extra == 'dev'
Requires-Dist: ruff>=0.14.14; extra == 'dev'
Description-Content-Type: text/markdown

# PlayerDataPy
A python package for interacting with the PlayerData GraphQL API.

## Folder Structure
- `playerdata_api`: The main package for interacting with the PlayerData API.
  - `gqlauth`: The main package for authenticating with the PlayerData API.
  - `gqlclient`: The main package for interacting with the PlayerData GraphQL API.
  - `custom_queries`: Custom queries for the PlayerData GraphQL API.
  - `custom_mutations`: Custom mutations for the PlayerData GraphQL API.
  - `custom_fields`: Custom fields for the PlayerData GraphQL API.
  - `input_types`: Input types for the PlayerData GraphQL API.
  - `enums`: Enums for the PlayerData GraphQL API.
  - `custom_typing_fields`: Custom typing fields for the PlayerData GraphQL API.
  - `custom_responses`: Custom responses for the PlayerData GraphQL API.

## Installation

uv is the tool we use to build and manage the `playerdatapy` Python package.

Make sure you install uv using [pipx](https://docs.astral.sh/uv/getting-started/installation/#pypi) or the [official installer](https://docs.astral.sh/uv/getting-started/installation/#standalone-installer). Installing with pip or other methods will lead to unexpected behavior.

We recommend using the [official installer](https://docs.astral.sh/uv/getting-started/installation/#standalone-installer).

Then you can install the required dependencies, in a virtual environment if required.

```bash
    uv sync
```

## Usage

To use the GraphqlClient, you need to provide your client id, this will be provided to you by PlayerData.
To request API credentials, please contact the PlayerData team at support@playerdata.co.uk.


### Option 1: Use generated types with PlayerDataAPI

Example usage of this option is provided in the `examples/pydantic/` folder.
The basic flow is to create a PlayerDataAPI instance, build the query objects using the code-generated Pydantic models (generated by ariadne-codegen), and then call the run_queries method.

For more detailed documentation, see [`examples/pydantic/README.md`](examples/pydantic/README.md).

To run an example of this option, you can use the following command:

```bash
python examples/pydantic/quick_start.py
```

To run this you will need to set the following environment variables or hardcode them in the file:
```bash
export CLIENT_ID=your_client_id
export CLIENT_SECRET=your_client_secret
export CLUB_ID=your_club_id
```

For a more in-depth example, please see the `examples/pydantic/example_use.ipynb` notebook.
This notebook demonstrates how to use the PlayerData API with Pydantic to query specifics such as session details, session metrics, and raw data.

### Option 2: Use the GraphqlClient class directly

Example usage of this option is provided in the `examples/direct/` folder.
The basic flow is to create a GraphqlClient instance, build the query string, and then call the query method.

For more detailed documentation, see [`examples/direct/README.md`](examples/direct/README.md).

To run an example of this option, you can use the following command:

```bash
python examples/direct/quick_start.py
```

To run this you will need to set the following environment variables or hardcode them in the file:
```bash
export CLIENT_ID=your_client_id
export CLIENT_SECRET=your_client_secret
export CLUB_ID=your_club_id
```

## Authentication Types

These authentication types are set out in the `playerdatapy.gqlauth.AuthenticationType` enum.
The default authentication type is `AuthenticationType.AUTHORISATION_CODE_FLOW`.
These authentication types are used to set the authentication type in the `GraphqlAuth` class.

### Authorisation Code Flow (PKCE)

Authorisation code flow with PKCE is used to authenticate users with non_confidential credentials.

### Authorisation Code Flow

Authorisation code flow is used to authenticate users with confidential credentials.

### Client Credentials Flow  

Client credentials flow is used to authenticate backend to backend communication.

### Updates to the API Fields and Mutations

To update the API fields and mutations, you need to set an `AUTH_TOKEN` environment variable.
This code is auto-generated by Ariadne, so any changes to the API fields and mutations will be reflected in the code.

```shell
export AUTH_TOKEN=f"Bearer {your_auth_token}"
python -m ariadne-codegen
```

This will generate code and update files in the `playerdatapy` package.
