### Install Python Client Dependencies with Poetry

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/AGENTS.md

Command to install project dependencies for the Python client using Poetry. Must be run from the client's directory.

```bash
# From client directory (requires Poetry)
cd clients/algoliasearch-client-python
poetry install                                 # Install dependencies
```

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

### Install Algolia Python API Client

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/README.md

Install the Algolia Python API Client using pip. Ensure you are using a compatible Python version (3.8+).

```bash
pip install --upgrade 'algoliasearch>=4.0,<5.0'
```

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

### Perform a Search Query

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/README.md

Fetch search results from your Algolia index. This example includes parameters like index name, query string, and the number of hits per page, with typo tolerance enabled.

```python
# Fetch search results, with typo tolerance
response = await _client.search(
    search_method_params={
        "requests": [
            {
                "indexName": "<YOUR_INDEX_NAME>",
                "query": "<YOUR_QUERY>",
                "hitsPerPage": 50,
            },
        ],
    },
)

# use the class directly
print(response)

# print the JSON response
print(response.to_json())
```

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

### Client Session Lifecycle Management

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/AGENTS.md

Demonstrates proper client session management by either explicitly closing the client or using an asynchronous context manager.

```python
# Always close the client or use context manager
client = SearchClient("APP_ID", "API_KEY")
try:
    await client.search(...)
finally:
    await client.close()

# Or prefer context manager
async with SearchClient("APP_ID", "API_KEY") as client:
    await client.search(...)
```

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

### Async Client Usage with Context Manager

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/AGENTS.md

Demonstrates the async-first design where all API methods are `async def`. Use `async with` for proper client lifecycle management.

```python
async with SearchClient("APP_ID", "API_KEY") as client:
    response = await client.search(...)
```

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

### Build Python Client

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/AGENTS.md

Command to build the Python client from the repository root. Requires the `yarn cli` tool.

```bash
# From repo root (api-clients-automation)
yarn cli build clients python                  # Build Python client
```

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

### Run Interactive Playground for Python Search

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/AGENTS.md

Command to launch an interactive playground for the Python search client. Requires the `yarn cli` tool.

```bash
# From repo root (api-clients-automation)
yarn cli playground python search              # Interactive playground
```

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

### Correct Async API Call

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/AGENTS.md

Shows the correct way to call asynchronous API methods using `await`. Incorrect usage outside an async context will not work.

```python
# CORRECT
response = await client.search(...)

# Or use asyncio.run() for scripts
import asyncio
asyncio.run(main())
```

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

### Run Python Client Tests with Poetry

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/AGENTS.md

Command to run tests for the Python client using Poetry. Must be run from the client's directory.

```bash
# From client directory (requires Poetry)
cd clients/algoliasearch-client-python
poetry run pytest                              # Run tests
```

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

### Verify Correct Repository

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/AGENTS.md

Before making any changes, check if you are in the correct repository. This command lists remote repositories.

```bash
git remote -v
```

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

### Initialize SearchClient and Save Object

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/README.md

Initialize the SearchClient with your Algolia App ID and API Key. This snippet demonstrates how to add a new record to an Algolia index and print the response.

```python
from algoliasearch.search.client import SearchClient

_client = SearchClient("YOUR_APP_ID", "YOUR_API_KEY")

# Add a new record to your Algolia index
response = await _client.save_object(
    index_name="<YOUR_INDEX_NAME>",
    body={
        "objectID": "id",
        "test": "val",
    },
)

# use the class directly
print(response)

# print the JSON response
print(response.to_json())
```

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

### Python Client Transporter Architecture

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/AGENTS.md

Illustrates the core transport mechanism in `algoliasearch/http/`. It includes retry logic and host failover.

```python
# Core transport in algoliasearch/http/
class Transporter(BaseTransporter):
    def __init__(self, config: BaseConfig):
        self._session: Optional[ClientSession] = None
        self._retry_strategy = RetryStrategy()

    async def request(self, verb, path, request_options, use_read_transporter):
        # Retry logic with host failover
```

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

### Format Python Client Code

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/AGENTS.md

Command to format the Python client code according to project standards. Requires the `yarn cli` tool.

```bash
# From repo root (api-clients-automation)
yarn cli format python clients/algoliasearch-client-python
```

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

### Type Check Python Client with Poetry

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/AGENTS.md

Command to perform type checking on the Python client code using Pyright via Poetry. Must be run from the client's directory.

```bash
# From client directory (requires Poetry)
cd clients/algoliasearch-client-python
poetry run pyright                             # Type check
```

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

### Type Narrowing with isinstance

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/AGENTS.md

Illustrates how to use `isinstance` for type checking when dealing with union types, specifically for narrowing down to a `Hit` object.

```python
# Use isinstance for union types
from algoliasearch.search.models import Hit

if isinstance(result, Hit):
    print(result.object_id)
```

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

### Run CTS Tests for Python

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/AGENTS.md

Command to run the generated Contract Test Suite (CTS) tests for the Python client. Requires the `yarn cli` tool.

```bash
# From repo root (api-clients-automation)
yarn cli cts run python                        # Run CTS tests
```

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

### Check If File Is Generated

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/AGENTS.md

Verify if a file is hand-written or generated by checking the `generation.config.mjs` file. Generated files should not be edited directly.

```javascript
// In generation.config.mjs - patterns WITHOUT '!' are GENERATED (do not edit)
'clients/algoliasearch-client-python/algoliasearch/**',              // Generated
'!clients/algoliasearch-client-python/algoliasearch/http/**',        // Hand-written ✓
```

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

### Generate CTS Tests for Python

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/AGENTS.md

Command to generate Contract Test Suite (CTS) tests for the Python client. Requires the `yarn cli` tool.

```bash
# From repo root (api-clients-automation)
yarn cli cts generate python                   # Generate CTS tests
```

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

### Wait for Task Completion

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/README.md

Poll the task status to confirm when a record has been indexed. This is useful for ensuring data consistency before proceeding.

```python
# Poll the task status to know when it has been indexed
await client.wait_for_task(index_name="<YOUR_INDEX_NAME>", task_id=response.task_id)
```

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

### Algolia Exception Hierarchy

Source: https://github.com/algolia/algoliasearch-client-python/blob/main/AGENTS.md

Outlines the base exception `AlgoliaException` and its derived exceptions for handling request failures and API errors.

```python
# algoliasearch/http/exceptions.py
AlgoliaException              # Base
├── RequestException          # Request failed
├── AlgoliaUnreachableHostException  # All hosts failed
└── AlgoliaApiException       # API error response
```

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