### Install spnkr Package

Source: https://github.com/acurtis166/spnkr/blob/master/docs/getting-started.md

Installs the spnkr Python package using pip. This is the initial step to begin using the library.

```shell
pip install spnkr
```

--------------------------------

### Refresh Player Tokens using spnkr

Source: https://github.com/acurtis166/spnkr/blob/master/docs/getting-started.md

This Python script demonstrates how to refresh OAuth2 tokens and obtain Spartan and Clearance tokens using the spnkr library. It requires aiohttp for asynchronous operations and specific Azure AD application credentials.

```python
import asyncio

from aiohttp import ClientSession

from spnkr import AzureApp, refresh_player_tokens

CLIENT_ID = "CLIENT_ID"
CLIENT_SECRET = "CLIENT_SECRET"
REDIRECT_URI = "REDIRECT_URI"
REFRESH_TOKEN = "REFRESH_TOKEN"


async def main() -> None:
    app = AzureApp(CLIENT_ID, CLIENT_SECRET, REDIRECT_URI)

    async with ClientSession() as session:
        player = await refresh_player_tokens(session, app, REFRESH_TOKEN)

    print(f"Spartan token: {player.spartan_token.token}")  # Valid for 4 hours.
    print(f"Clearance token: {player.clearance_token.token}")
    print(f"Xbox Live player ID (XUID): {player.player_id}")
    print(f"Xbox Live gamertag: {player.gamertag}")
    print(f"Xbox Live authorization: {player.xbl_authorization_header_value}")


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Authenticate Player with Azure AD

Source: https://github.com/acurtis166/spnkr/blob/master/docs/getting-started.md

Performs an initial OAuth2 authentication flow to obtain a refresh token using Azure AD credentials. This script requires the `spnkr` and `aiohttp` libraries and uses `asyncio` for asynchronous operations. It takes `CLIENT_ID`, `CLIENT_SECRET`, and `REDIRECT_URI` as inputs.

```Python
import asyncio

from aiohttp import ClientSession

from spnkr import AzureApp, authenticate_player

CLIENT_ID = "CLIENT_ID"
CLIENT_SECRET = "CLIENT_SECRET"
REDIRECT_URI = "REDIRECT_URI"


async def main() -> None:
    app = AzureApp(CLIENT_ID, CLIENT_SECRET, REDIRECT_URI)

    async with ClientSession() as session:
        refresh_token = await authenticate_player(session, app)

    print(f"Your refresh token is:\n{refresh_token}")


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Request Player Match History

Source: https://github.com/acurtis166/spnkr/blob/master/docs/basic-usage.md

Shows how to retrieve a player's match history using the initialized HaloInfiniteClient and parse the response into Pydantic models. It illustrates accessing match details like the start time.

```python
import asyncio

from aiohttp import ClientSession
from spnkr import HaloInfiniteClient

# Any of the following are acceptable for the below request.
PLAYER = "xuid(1234567890123456)"  # AuthenticatedPlayer.player_id
PLAYER = "1234567890123456"
PLAYER = 1234567890123456
PLAYER = "MyGamertag"  # AuthenticatedPlayer.gamertag


async def main() -> None:
    async with ClientSession() as session:
        client = HaloInfiniteClient(...)

        # Request the 25 most recent matches for the player.
        resp = await client.stats.get_match_history(PLAYER)
        # Parse the response JSON into a Pydantic model
        history = await resp.parse()

        # Get the most recent match played and print the start time.
        last_match_info = history.results[0].match_info
        print(f"Last match played on {last_match_info.start_time:%Y-%m-%d}")


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Get Match History

Source: https://github.com/acurtis166/spnkr/blob/master/docs/basic-usage.md

Retrieves the match history for a given player. The player can be identified by their XUID, Gamertag, or a numeric ID. The response can be parsed into Pydantic models.

```APIDOC
## Get Match History

### Description
Fetches the match history for a specified player. The player can be identified in multiple ways (XUID, Gamertag, numeric ID). The response data can be parsed into Pydantic models using the `parse()` method.

### Method
GET

### Endpoint
`/stats/get_match_history/{player}`

### Parameters
#### Path Parameters
- **player** (str | int) - Required - The identifier for the player (e.g., `xuid(1234567890123456)`, `1234567890123456`, `MyGamertag`).

#### Request Example
```python
import asyncio

from aiohttp import ClientSession
from spnkr import HaloInfiniteClient

PLAYER = "MyGamertag" # Or any valid player identifier

async def main() -> None:
    async with ClientSession() as session:
        client = HaloInfiniteClient(session=session, spartan_token="SPARTAN_TOKEN", clearance_token="CLEARANCE_TOKEN")

        resp = await client.stats.get_match_history(PLAYER)
        history = await resp.parse() # Parses response into Pydantic models

        last_match_info = history.results[0].match_info
        print(f"Last match played on {last_match_info.start_time:%Y-%m-%d}")


if __name__ == "__main__":
    asyncio.run(main())
```

### Response
#### Success Response (200)
- **results** (list) - A list of match history entries.
- **paging_info** (object) - Information about pagination.

#### Response Example
```json
{
  "results": [
    {
      "match_info": {
        "start_time": "2024-01-01T10:00:00Z"
      }
    }
  ],
  "paging_info": {}
}
```
```

--------------------------------

### Initializing HaloInfiniteClient

Source: https://github.com/acurtis166/spnkr/blob/master/docs/basic-usage.md

Demonstrates how to create an instance of HaloInfiniteClient using aiohttp.ClientSession and authentication tokens. It also shows how to configure the request rate limit.

```APIDOC
## Initializing HaloInfiniteClient

### Description
Initializes the `HaloInfiniteClient` with a provided `aiohttp.ClientSession` and Spartan/Clearance tokens. Optionally, you can set the `requests_per_second` limit.

### Method
POST

### Endpoint
`/`

### Parameters
#### Request Body
- **session** (aiohttp.ClientSession) - Required - The client session to use for requests.
- **spartan_token** (str) - Required - The Spartan authentication token.
- **clearance_token** (str) - Required - The Clearance authentication token.
- **requests_per_second** (int) - Optional - The maximum number of requests allowed per second (defaults to 5).

### Request Example
```python
import asyncio

from aiohttp import ClientSession
from spnkr import HaloInfiniteClient


async def main() -> None:
    async with ClientSession() as session:
        client = HaloInfiniteClient(
            session=session,
            spartan_token="SPARTAN_TOKEN",
            clearance_token="CLEARANCE_TOKEN",
            requests_per_second=5,
        )


if __name__ == "__main__":
    asyncio.run(main())
```

### Response
#### Success Response (200)
N/A (Initializes the client object)

#### Response Example
N/A
```

--------------------------------

### Initialize HaloInfiniteClient with aiohttp

Source: https://github.com/acurtis166/spnkr/blob/master/docs/basic-usage.md

Demonstrates how to create an instance of HaloInfiniteClient using aiohttp.ClientSession and authentication tokens. It also shows how to optionally set the requests per second rate limit.

```python
import asyncio

from aiohttp import ClientSession
from spnkr import HaloInfiniteClient


async def main() -> None:
    async with ClientSession() as session:
        client = HaloInfiniteClient(
            session=session,
            spartan_token="SPARTAN_TOKEN",
            clearance_token="CLEARANCE_TOKEN",
            # Optional, default rate is 5.
            requests_per_second=5,
        )


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Add HaloInfiniteClient Methods for User and Service Data

Source: https://github.com/acurtis166/spnkr/blob/master/CHANGES.md

Introduces new methods to the HaloInfiniteClient for retrieving service records and user information. These methods support fetching users by gamertag or ID, and include parsing logic for the returned data. Gamertags can now be used directly with 'stats' client methods.

```python
HaloInfiniteClient.get_service_record
HaloInfiniteClient.get_current_user
HaloInfiniteClient.get_user_by_gamertag
HaloInfiniteClient.get_user_by_id
HaloInfiniteClient.get_users_by_id
```

--------------------------------

### Implement Caching with aiohttp-client-cache

Source: https://github.com/acurtis166/spnkr/blob/master/docs/basic-usage.md

Demonstrates how to integrate caching with spnkr using the aiohttp-client-cache package. It shows setting up a SQLite backend with a custom filter to cache only responses with a 'Cache-Control' header.

```python
from aiohttp_client_cache import CachedSession, SQLiteBackend
from spnkr import HaloInfiniteClient


async def filter_by_cache_control(response):
    """Only cache responses with a cache-control header."""
    return "Cache-Control" in response.headers


async def main() -> None:
    cache = SQLiteBackend(
        "cache.sqlite",
        cache_control=True,
        filter_fn=filter_by_cache_control,
    )
    async with CachedSession(cache=cache) as session:
        client = HaloInfiniteClient(...)


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Update HaloInfiniteClient for Service Grouping and Rate Limiting

Source: https://github.com/acurtis166/spnkr/blob/master/CHANGES.md

Refactors the HaloInfiniteClient to group endpoints by URL hosts, creating a 'services' module. This change moves data retrieval methods to respective service classes, with HaloInfiniteClient acting as an indirect entrypoint via cached service properties. The design facilitates adding new services and enables per-host rate limiting.

```python
HaloInfiniteClient.gamecms_hacs
HaloInfiniteClient.profile
HaloInfiniteClient.discovery_ugc
HaloInfiniteClient.skill
HaloInfiniteClient.stats
```

--------------------------------

### Add New Mappings and Enum Entries to SPNKr Tools

Source: https://github.com/acurtis166/spnkr/blob/master/CHANGES.md

Introduces new mappings, 'BOT_MAP' and 'TEAM_MAP', to the 'tools' module for enhanced functionality. New enum entries have also been added, derived from the HaloWaypoint JavaScript code, to support expanded data representation.

```python
tools module
BOT_MAP
TEAM_MAP
New enum entries
```

--------------------------------

### Caching with CachedSession

Source: https://github.com/acurtis166/spnkr/blob/master/docs/basic-usage.md

Illustrates how to configure and use `aiohttp_client_cache.CachedSession` for caching API responses, reducing redundant requests. It shows a filter function to cache only responses with a 'Cache-Control' header.

```APIDOC
## Caching with CachedSession

### Description
Enables caching of API responses by using `aiohttp_client_cache.CachedSession`. This example demonstrates setting up a SQLite backend and filtering responses to cache only those with a 'Cache-Control' header.

### Method
GET

### Endpoint
`/` (Applies to all requests made through the cached session)

### Parameters
#### Request Body
- **session** (aiohttp.ClientSession) - Required - The client session to use for requests.
- **spartan_token** (str) - Required - The Spartan authentication token.
- **clearance_token** (str) - Required - The Clearance authentication token.

### Request Example
```python
from aiohttp_client_cache import CachedSession, SQLiteBackend
from spnkr import HaloInfiniteClient

def filter_by_cache_control(response):
    """Only cache responses with a cache-control header."""
    return "Cache-Control" in response.headers

async def main() -> None:
    cache = SQLiteBackend(
        "cache.sqlite",
        cache_control=True,
        filter_fn=filter_by_cache_control,
    )
    async with CachedSession(cache=cache) as session:
        client = HaloInfiniteClient(session=session, spartan_token="SPARTAN_TOKEN", clearance_token="CLEARANCE_TOKEN")
        # Subsequent requests made with this client will be cached according to the configuration


if __name__ == "__main__":
    asyncio.run(main())
```

### Response
#### Success Response (200)
Responses are cached based on the `filter_fn` and `cache_control` settings of the `SQLiteBackend`.

#### Response Example
N/A (This example focuses on the setup of caching)
```

--------------------------------

### Refine XUID Handling and Parameter Naming in SPNKr

Source: https://github.com/acurtis166/spnkr/blob/master/CHANGES.md

Implements stricter XUID wrapping and unwrapping logic. The 'xuid' parameter in 'stats' client methods has been renamed to 'player' for clarity and consistency. This change affects methods related to match counts, history, service records, and stats.

```python
stats client methods (`get_match_count`, `get_match_history`, `get_service_record`, `get_match_stats`)
```

--------------------------------

### Fix Pydantic Parsing for MapLink Attribute

Source: https://github.com/acurtis166/spnkr/blob/master/CHANGES.md

Resolves an issue in Pydantic parsing by allowing 'None' for the 'map_link' attribute within 'MapModePair'. This ensures that entries without a map link are handled correctly without causing parsing errors.

```python
MapModePair.map_link
```

--------------------------------

### Update Enum Values for Accuracy in SPNKr

Source: https://github.com/acurtis166/spnkr/blob/master/CHANGES.md

Corrects the 'Tier.NOT_APPLICABLE' enum value to 'Tier.UNRANKED' to improve accuracy in representing player ranks. Additionally, 'SubTier' enum values have been adjusted to be zero-based and increase with CSR (Competitive Skill Rating).

```python
Tier.NOT_APPLICABLE -> Tier.UNRANKED
SubTier enum values
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.