Skip to content

Commit 5e237b8

Browse files
elliotgPDelliotgPD
committed
feat: add and update README files
1 parent 0dccea7 commit 5e237b8

3 files changed

Lines changed: 281 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,10 +38,12 @@ To request API credentials, please contact the PlayerData team at support@player
3838
Example usage of this option is provided in the `examples/pydantic/` folder.
3939
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.
4040

41+
For more detailed documentation, see [`examples/pydantic/README.md`](examples/pydantic/README.md).
42+
4143
To run an example of this option, you can use the following command:
4244

4345
```bash
44-
python examples/pydantic/sessions_query.py
46+
python examples/pydantic/quick_start.py
4547
```
4648

4749
To run this you will need to set the following environment variables or hardcode them in the file:
@@ -51,16 +53,20 @@ export CLIENT_SECRET=your_client_secret
5153
export CLUB_ID=your_club_id
5254
```
5355

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

5559
### Option 2: Use the GraphqlClient class directly
5660

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

64+
For more detailed documentation, see [`examples/direct/README.md`](examples/direct/README.md).
65+
6066
To run an example of this option, you can use the following command:
6167

6268
```bash
63-
python examples/direct/sessions_query.py
69+
python examples/direct/quick_start.py
6470
```
6571

6672
To run this you will need to set the following environment variables or hardcode them in the file:

‎examples/direct/README.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Direct GraphQL Examples
2+
3+
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.
4+
5+
## Overview
6+
7+
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.
8+
9+
## Quick Start
10+
11+
The simplest way to get started is with the `quick_start.py` example:
12+
13+
```bash
14+
python examples/direct/quick_start.py
15+
```
16+
17+
Before running, set the following environment variables:
18+
19+
```bash
20+
export CLIENT_ID=your_client_id
21+
export CLIENT_SECRET=your_client_secret
22+
export CLUB_ID=your_club_id
23+
```
24+
25+
## Basic Usage Pattern
26+
27+
```python
28+
from playerdatapy.gqlauth import GraphqlAuth, AuthenticationType
29+
from playerdatapy.gqlclient import Client
30+
from playerdatapy.constants import API_BASE_URL
31+
import asyncio
32+
33+
# Authenticate
34+
auth = GraphqlAuth(
35+
client_id=CLIENT_ID,
36+
client_secret=CLIENT_SECRET,
37+
type=AuthenticationType.CLIENT_CREDENTIALS_FLOW,
38+
)
39+
40+
# Create a Client instance
41+
client = Client(
42+
url=f"{API_BASE_URL}/api/graphql",
43+
headers={"Authorization": f"Bearer {auth._get_authentication_token()}"},
44+
)
45+
46+
# Build your GraphQL query string
47+
query = """
48+
query($clubIdEq:ID!,$startTimeGteq:ISO8601DateTime,$endTimeLteq:ISO8601DateTime){
49+
sessions(filter: {clubIdEq:$clubIdEq, startTimeGteq:$startTimeGteq, endTimeLteq:$endTimeLteq}){
50+
id
51+
startTime
52+
endTime
53+
}
54+
}
55+
"""
56+
57+
# Define variables
58+
variables = {
59+
"clubIdEq": CLUB_ID,
60+
"startTimeGteq": start_time,
61+
"endTimeLteq": end_time,
62+
}
63+
64+
# Execute the query
65+
async def main():
66+
response = client.execute(query=query, variables=variables)
67+
result = await client.get_data(response)
68+
print(result["sessions"])
69+
70+
asyncio.run(main())
71+
```
72+
73+
## Building Queries
74+
75+
When building GraphQL queries, you can use the GraphiQL Playground at https://app.playerdata.co.uk/api/graphiql/ to:
76+
- Test queries interactively
77+
- Explore the schema
78+
- Validate query syntax
79+
- See example queries
80+
81+
The playground provides autocomplete and schema documentation to help you build queries efficiently.
82+
83+
## Example Query
84+
85+
The `quick_start.py` example demonstrates querying sessions filtered by time range:
86+
87+
```graphql
88+
query($clubIdEq:ID!,$startTimeGteq:ISO8601DateTime,$endTimeLteq:ISO8601DateTime){
89+
sessions(filter: {clubIdEq:$clubIdEq, startTimeGteq:$startTimeGteq, endTimeLteq:$endTimeLteq}){
90+
id
91+
startTime
92+
endTime
93+
}
94+
}
95+
```
96+
97+
This query:
98+
- Takes a club ID and time range as variables
99+
- Filters sessions by club ID and time range
100+
- Returns session ID, start time, and end time
101+
102+
## Authentication Types
103+
104+
The examples use `AuthenticationType.CLIENT_CREDENTIALS_FLOW` by default, which is suitable for backend-to-backend communication. You can also use:
105+
106+
- `AuthenticationType.AUTHORISATION_CODE_FLOW`: For confidential client credentials
107+
- `AuthenticationType.AUTHORISATION_CODE_FLOW_PKCE`: For non-confidential client credentials
108+
109+
## When to Use Direct GraphQL
110+
111+
Use the direct GraphQL approach when:
112+
- You need full control over query strings
113+
- You're migrating existing GraphQL queries
114+
- You want to use queries from external tools or documentation
115+
- You prefer working with raw GraphQL syntax
116+
117+
For type-safe queries with autocomplete support, consider using the [Pydantic examples](../pydantic/) instead.

‎examples/pydantic/README.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Pydantic Examples
2+
3+
This folder contains examples demonstrating how to use PlayerDataPy with generated Pydantic types via the `PlayerDataAPI` class. This approach provides type safety and autocomplete support through code-generated models.
4+
5+
## Overview
6+
7+
The `PlayerDataAPI` class wraps the GraphQL client and provides a high-level interface for building queries using Pydantic models. These models are auto-generated by `ariadne-codegen` and provide type-safe query construction.
8+
9+
## Quick Start
10+
11+
The simplest way to get started is with the `quick_start.py` example:
12+
13+
```bash
14+
python examples/pydantic/quick_start.py
15+
```
16+
17+
Before running, set the following environment variables:
18+
19+
```bash
20+
export CLIENT_ID=your_client_id
21+
export CLIENT_SECRET=your_client_secret
22+
export CLUB_ID=your_club_id
23+
```
24+
25+
## Structure
26+
27+
- **`quick_start.py`**: A simple example demonstrating basic query execution
28+
- **`example_use.ipynb`**: A comprehensive Jupyter notebook with detailed examples covering:
29+
- Session details queries
30+
- Session metrics queries
31+
- Raw data retrieval and processing
32+
- **`queries/`**: Reusable query functions built using Pydantic models
33+
- `club_sessions_filtered_by_time_range.py`: Query sessions filtered by time range
34+
- `session_details.py`: Query detailed session information including participants and segments
35+
- `session_metrics.py`: Query session and participation metrics
36+
- `session_participations_urls.py`: Query datafile URLs for session participations
37+
- **`raw_data_utils/`**: Utilities for processing raw data
38+
- `url_to_csv.py`: Functions to fetch raw data from URLs and convert to CSV format
39+
40+
## Basic Usage Pattern
41+
42+
```python
43+
from playerdatapy.playerdata_api import PlayerDataAPI
44+
from playerdatapy.gqlauth import AuthenticationType
45+
import asyncio
46+
47+
# Create a PlayerDataAPI instance
48+
api = PlayerDataAPI(
49+
client_id=CLIENT_ID,
50+
client_secret=CLIENT_SECRET,
51+
authentication_type=AuthenticationType.CLIENT_CREDENTIALS_FLOW,
52+
)
53+
54+
# Build queries using Pydantic models
55+
from queries.club_sessions_filtered_by_time_range import club_sessions_filtered_by_time_range
56+
57+
query = club_sessions_filtered_by_time_range(
58+
club_id=CLUB_ID,
59+
start_time_gteq=START_TIME,
60+
end_time_lteq=END_TIME,
61+
)
62+
63+
# Execute queries
64+
response = asyncio.run(
65+
api.run_queries("ClubSessionsFilteredByTimeRangeQuery", query)
66+
)
67+
```
68+
69+
## Query Functions
70+
71+
The `queries/` folder contains reusable query functions that demonstrate common use cases:
72+
73+
### Club Sessions Filtered by Time Range
74+
75+
Query sessions for a club within a specific time range:
76+
77+
```python
78+
from queries.club_sessions_filtered_by_time_range import club_sessions_filtered_by_time_range
79+
80+
query = club_sessions_filtered_by_time_range(
81+
club_id="your_club_id",
82+
start_time_gteq=datetime.now() - timedelta(days=30),
83+
end_time_lteq=datetime.now(),
84+
)
85+
```
86+
87+
### Session Details
88+
89+
Query detailed information about a session including participants, athletes, and segments:
90+
91+
```python
92+
from queries.session_details import session_details
93+
94+
query = session_details(session_id="your_session_id")
95+
```
96+
97+
### Session Metrics
98+
99+
Query metrics for a session, including aggregated session metrics and per-participation metrics:
100+
101+
```python
102+
from queries.session_metrics import session_metrics
103+
104+
query = session_metrics(session_id="your_session_id")
105+
```
106+
107+
### Session Participation URLs
108+
109+
Query datafile URLs for session participations:
110+
111+
```python
112+
from queries.session_participations_urls import session_participations_urls
113+
114+
query = session_participations_urls(
115+
session_participation_ids=["id1", "id2", "id3"]
116+
)
117+
```
118+
119+
## Raw Data Processing
120+
121+
The `raw_data_utils/` folder contains utilities for processing raw data retrieved from the API:
122+
123+
### Converting Raw Data to CSV
124+
125+
The `url_to_csv.py` module provides functions to:
126+
- Fetch JSON data from URLs
127+
- Extract GPS data, IMU acceleration data, and IMU orientation data
128+
- Write data to CSV files organized by session participation ID
129+
130+
Example usage:
131+
132+
```python
133+
from raw_data_utils.url_to_csv import url_to_csv
134+
135+
# Fetch and convert raw data to CSV files
136+
url_to_csv(
137+
url="https://datafile_url.com",
138+
session_participation_id="participation_id"
139+
)
140+
```
141+
142+
This will create a directory named after the `session_participation_id` containing:
143+
- `gps_data_{session_participation_id}.csv`
144+
- `imu_acceleration_data_{session_participation_id}.csv`
145+
- `imu_orientation_data_{session_participation_id}.csv`
146+
147+
## Authentication Types
148+
149+
The examples use `AuthenticationType.CLIENT_CREDENTIALS_FLOW` by default, which is suitable for backend-to-backend communication. You can also use:
150+
151+
- `AuthenticationType.AUTHORISATION_CODE_FLOW`: For confidential client credentials
152+
- `AuthenticationType.AUTHORISATION_CODE_FLOW_PKCE`: For non-confidential client credentials
153+
154+
## Further Reading
155+
156+
For more detailed examples and use cases, see the `example_use.ipynb` notebook which provides comprehensive demonstrations of querying session details, metrics, and raw data processing.

0 commit comments

Comments
 (0)