playerdatapy 1.8.1__tar.gz

playerdatapy-1.8.1/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: PlayerDataPy CI
+
+on:
+  pull_request:
+      types: [opened, synchronize, reopened, ready_for_review]
+  push:
+    branches: [ main ]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint
+    secrets: inherit
+    uses: "./.github/workflows/lint.yml"
+
+  test:
+    name: Test
+    secrets: inherit
+    uses: "./.github/workflows/test.yml"
+
+  release:
+    name: Release
+    secrets: inherit
+    needs: [lint, test]
+    uses: "./.github/workflows/release.yml"
+  
+  publish:
+    name: Publish playerDatapy Python Package
+    secrets: inherit
+    needs: release
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: "./.github/workflows/publish.yml"
+    with:
+      new_release_published: ${{ needs.release.outputs.new_release_published }}
+      new_release_version: ${{ needs.release.outputs.new_release_version }}

playerdatapy-1.8.1/.github/workflows/lint.yml

@@ -0,0 +1,35 @@
+name: PlayerDataPy Lint
+
+on:
+  workflow_call: {}
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        id: setup-uv
+        uses: astral-sh/setup-uv@v6.6.1
+        with:
+          enable-cache: true
+          cache-suffix: '-venv-lint'
+          activate-environment: true
+
+      - name: Install Dependencies
+        run: uv sync --extra dev --locked
+
+      - name: Lint Check (Ruff)
+        run: uv run --no-sync ruff check .
+
+      - name: Format Check (Ruff)
+        run: uv run --no-sync ruff format --check .

playerdatapy-1.8.1/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish Python
+
+on:
+  workflow_call:
+    inputs:
+      new_release_published:
+        description: 'Whether a new release has been published'
+        required: true
+        type: string
+      new_release_version:
+        description: 'The latest release version'
+        required: true
+        type: string
+
+jobs:
+  publish:
+    name: Publish Python Package
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    environment:
+      name: pypi
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7.2.1
+        with:
+          enable-cache: true
+          cache-suffix: '-publish'
+          activate-environment: true
+
+      - name: Apply Semantic Version
+        if: ${{ inputs.new_release_published == 'true' }}
+        run: uv version ${{ inputs.new_release_version }}
+
+      - name: Build
+        if: ${{ inputs.new_release_published == 'true' }}
+        run: uv build
+
+      - name: Publish
+        if: ${{ inputs.new_release_published == 'true' }}
+        run: uv publish --trusted-publishing always
+

playerdatapy-1.8.1/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: PlayerDataPy Release
+
+on:
+  workflow_call:
+    outputs:
+      new_release_published:
+        value: ${{ jobs.release.outputs.new_release_published }}
+      new_release_version:
+        value: ${{ jobs.release.outputs.new_release_version }}
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      
+      - name: Semantic Release
+        id: semantic-release
+        uses: cycjimmy/semantic-release-action@v4
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    outputs:
+      new_release_published: ${{ steps.semantic-release.outputs.new_release_published }}
+      new_release_version: ${{ steps.semantic-release.outputs.new_release_version }}

playerdatapy-1.8.1/.github/workflows/test.yml

@@ -0,0 +1,32 @@
+name: PlayerDataPy Test
+
+on:
+  workflow_call: {}
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        id: setup-uv
+        uses: astral-sh/setup-uv@v6.6.1
+        with:
+          enable-cache: true
+          cache-suffix: '-venv-test'
+          activate-environment: true
+
+      - name: Install Dependencies
+        run: uv sync --extra dev --locked
+
+      - name: Run Tests
+        run: uv run --no-sync pytest

playerdatapy-1.8.1/.gitignore

@@ -0,0 +1,24 @@
+__pycache__/
+
+.token
+.vscode
+.vscode
+.python-version
+key.json
+.DS_Store
+venv
+.venv
+.idea
+__pycache__
+__PYCACHE__
+.pytest_cache
+.mypy_cache
+.ipynb_checkpoints
+*.egg-info/
+*.pyc
+*.mp4
+*.rrd
+*.edgeblob
+*.glb
+.coverage
+.token

playerdatapy-1.8.1/.releaserc.json

@@ -0,0 +1,34 @@
+{
+  "branches": ["main"],
+  "plugins": [
+    [
+      "@semantic-release/commit-analyzer",
+      {
+        "preset": "angular",
+        "releaseRules": [
+          {
+            "type": "chore",
+            "release": "patch"
+          },
+          {
+            "type": "feat",
+            "release": "minor"
+          },
+          {
+            "type": "fix",
+            "release": "patch"
+          }
+        ]
+      }
+    ],
+    "@semantic-release/release-notes-generator",
+    [
+      "@semantic-release/github",
+      {
+        "successComment": false,
+        "failComment": false,
+        "failTitle": false
+      }
+    ]
+  ]
+}

playerdatapy-1.8.1/CODEOWNERS

@@ -0,0 +1 @@
+*   @playerdata/data-analysis

playerdatapy-1.8.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PlayerData
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

playerdatapy-1.8.1/PKG-INFO

@@ -0,0 +1,128 @@
+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.

playerdatapy-1.8.1/README.md

@@ -0,0 +1,107 @@
+# 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.

playerdatapy-1.8.1/examples/direct/README.md

@@ -0,0 +1,117 @@
+# Direct GraphQL Examples
+
+This folder contains examples demonstrating how to use PlayerDataPy by directly interacting with the `GraphqlClient` class. This approach gives you full control over GraphQL query strings and is useful when you need fine-grained control or want to use queries from external sources.
+
+## Overview
+
+The direct approach uses the `GraphqlClient` class to execute raw GraphQL query strings. This method is more flexible but requires you to manually construct GraphQL queries and handle the response structure.
+
+## Quick Start
+
+The simplest way to get started is with the `quick_start.py` example:
+
+```bash
+python examples/direct/quick_start.py
+```
+
+Before running, set the following environment variables:
+
+```bash
+export CLIENT_ID=your_client_id
+export CLIENT_SECRET=your_client_secret
+export CLUB_ID=your_club_id
+```
+
+## Basic Usage Pattern
+
+```python
+from playerdatapy.gqlauth import GraphqlAuth, AuthenticationType
+from playerdatapy.gqlclient import Client
+from playerdatapy.constants import API_BASE_URL
+import asyncio
+
+# Authenticate
+auth = GraphqlAuth(
+    client_id=CLIENT_ID,
+    client_secret=CLIENT_SECRET,
+    type=AuthenticationType.CLIENT_CREDENTIALS_FLOW,
+)
+
+# Create a Client instance
+client = Client(
+    url=f"{API_BASE_URL}/api/graphql",
+    headers={"Authorization": f"Bearer {auth._get_authentication_token()}"},
+)
+
+# Build your GraphQL query string
+query = """
+query($clubIdEq:ID!,$startTimeGteq:ISO8601DateTime,$endTimeLteq:ISO8601DateTime){
+  sessions(filter: {clubIdEq:$clubIdEq, startTimeGteq:$startTimeGteq, endTimeLteq:$endTimeLteq}){
+    id
+    startTime
+    endTime
+  }
+}
+"""
+
+# Define variables
+variables = {
+    "clubIdEq": CLUB_ID,
+    "startTimeGteq": start_time,
+    "endTimeLteq": end_time,
+}
+
+# Execute the query
+async def main():
+    response = client.execute(query=query, variables=variables)
+    result = await client.get_data(response)
+    print(result["sessions"])
+
+asyncio.run(main())
+```
+
+## Building Queries
+
+When building GraphQL queries, you can use the GraphiQL Playground at https://app.playerdata.co.uk/api/graphiql/ to:
+- Test queries interactively
+- Explore the schema
+- Validate query syntax
+- See example queries
+
+The playground provides autocomplete and schema documentation to help you build queries efficiently.
+
+## Example Query
+
+The `quick_start.py` example demonstrates querying sessions filtered by time range:
+
+```graphql
+query($clubIdEq:ID!,$startTimeGteq:ISO8601DateTime,$endTimeLteq:ISO8601DateTime){
+  sessions(filter: {clubIdEq:$clubIdEq, startTimeGteq:$startTimeGteq, endTimeLteq:$endTimeLteq}){
+    id
+    startTime
+    endTime
+  }
+}
+```
+
+This query:
+- Takes a club ID and time range as variables
+- Filters sessions by club ID and time range
+- Returns session ID, start time, and end time
+
+## Authentication Types
+
+The examples use `AuthenticationType.CLIENT_CREDENTIALS_FLOW` by default, which is suitable for backend-to-backend communication. You can also use:
+
+- `AuthenticationType.AUTHORISATION_CODE_FLOW`: For confidential client credentials
+- `AuthenticationType.AUTHORISATION_CODE_FLOW_PKCE`: For non-confidential client credentials
+
+## When to Use Direct GraphQL
+
+Use the direct GraphQL approach when:
+- You need full control over query strings
+- You're migrating existing GraphQL queries
+- You want to use queries from external tools or documentation
+- You prefer working with raw GraphQL syntax
+
+For type-safe queries with autocomplete support, consider using the [Pydantic examples](../pydantic/) instead.