### Install uv Package Manager

Source: https://github.com/dclimate/py-hamt/blob/main/AGENTS.md

Command to install the uv package manager if it's not already present on the system.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

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

### Sync Project Dependencies with uv

Source: https://github.com/dclimate/py-hamt/blob/main/AGENTS.md

Command to install all project dependencies using uv, typically after cloning the repository.

```bash
uv sync
```

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

### Set up py-hamt development environment

Source: https://github.com/dclimate/py-hamt/blob/main/README.md

Commands to set up the project virtual environment and install pre-commit hooks using uv.

```Shell
uv sync
source .venv/bin/activate
pre-commit install
```

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

### Install Git Pre-Commit Hooks

Source: https://github.com/dclimate/py-hamt/blob/main/AGENTS.md

Command to install pre-commit hooks, ensuring code quality checks run automatically before commits.

```bash
pre-commit install
```

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

### Install py-hamt using pip

Source: https://github.com/dclimate/py-hamt/blob/main/README.md

Instructions to install the py-hamt library using pip.

```Shell
pip install py-hamt
```

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

### Run All Project Tests with IPFS

Source: https://github.com/dclimate/py-hamt/blob/main/AGENTS.md

Executes all tests, including integration tests that require a running IPFS daemon.

```bash
pytest --ipfs
```

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

### Run Tests with Coverage and IPFS

Source: https://github.com/dclimate/py-hamt/blob/main/AGENTS.md

Executes all tests with code coverage reporting, including integration tests requiring IPFS.

```bash
pytest --ipfs --cov
```

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

### Run All Programmatic Checks

Source: https://github.com/dclimate/py-hamt/blob/main/AGENTS.md

Executes a script that performs various code quality and testing checks, assuming IPFS is running.

```bash
bash run-checks.sh
```

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

### Activate Python Virtual Environment

Source: https://github.com/dclimate/py-hamt/blob/main/AGENTS.md

Command to activate the Python virtual environment created by uv, making project dependencies available.

```bash
source .venv/bin/activate
```

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

### Add and Remove Dependencies using uv

Source: https://github.com/dclimate/py-hamt/blob/main/README.md

Demonstrates how to add new dependencies to your project and remove existing ones using the `uv` command. Examples include adding a standard package and a package to a specific development group.

```Shell
uv add numpy
```

```Shell
uv add pytest --group dev
```

```Shell
uv remove <package_name>
```

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

### Using py-hamt for Zarr Storage

Source: https://github.com/dclimate/py-hamt/blob/main/Architecture.md

This example illustrates how to use py-hamt as a backend for Zarr storage. It configures the HAMT to handle byte values and then initializes a ZarrHAMTStore, which can be passed to a Zarr dataset for serialization.

```python
hamt = await HAMT.build(cas=kubo_cas, values_are_bytes=True)
zarr_store = ZarrHAMTStore(hamt, read_only=False)
dataset.to_zarr(store=zarr_store, zarr_format=3)
```

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

### Run Specific Test File

Source: https://github.com/dclimate/py-hamt/blob/main/AGENTS.md

Command to execute tests from a single, specified test file within the `/tests` directory.

```bash
pytest test tests/<insert_file_here>
```

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

### Run Pre-Commit Checks Manually (No IPFS)

Source: https://github.com/dclimate/py-hamt/blob/main/AGENTS.md

Manually runs all pre-commit checks and displays differences, used when `run-checks.sh` cannot be run due to missing IPFS.

```bash
uv run pre-commit run --all-files --show-diff-on-failure
```

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

### Run Tests with Coverage (No IPFS)

Source: https://github.com/dclimate/py-hamt/blob/main/AGENTS.md

Executes all tests with code coverage reporting, skipping integration tests that require IPFS. Use this if IPFS is not available.

```bash
pytest --cov
```

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

### Auto-fix Ruff Formatting Errors

Source: https://github.com/dclimate/py-hamt/blob/main/AGENTS.md

Command to automatically fix formatting issues detected by Ruff, if they can be autofixed.

```bash
uv run ruff check --fix
```

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

### Generate py-hamt API documentation locally

Source: https://github.com/dclimate/py-hamt/blob/main/README.md

Command to generate and preview the py-hamt documentation locally using pdoc.

```Shell
uv run pdoc py_hamt
```

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

### Run py-hamt tests with IPFS configurations

Source: https://github.com/dclimate/py-hamt/blob/main/README.md

Commands to run py-hamt tests, demonstrating different behaviors based on the presence of a local IPFS daemon or Docker. Includes options for full integration tests or quick unit tests.

```Shell
uv run pytest --ipfs
```

```Shell
pytest --ipfs
```

```Shell
pytest
```

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

### Python In-Memory Content-Addressed Store for Testing

Source: https://github.com/dclimate/py-hamt/blob/main/Architecture.md

A testing implementation of ContentAddressedStore that uses an in-memory dictionary. Content is addressed via Blake3 hashing, providing a lightweight and fast solution for development and testing.

```APIDOC
InMemoryCAS Class (store.py:37)
  - Implements ContentAddressedStore
  - Backend: In-memory dictionary
  - Content Addressing: Blake3 hashing
```

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

### Python Kubo IPFS Content-Addressed Store

Source: https://github.com/dclimate/py-hamt/blob/main/Architecture.md

An IPFS implementation of ContentAddressedStore, leveraging the Kubo daemon. It uses RPC for writes and HTTP Gateway for reads, supporting authentication, custom headers, connection pooling, and concurrency limiting.

```APIDOC
KuboCAS Class (store.py:74)
  - Implements ContentAddressedStore
  - Backend: IPFS (Kubo daemon)
  - Write Operations: RPC API (/api/v0/add)
  - Read Operations: HTTP Gateway (/ipfs/{cid})
  - Features:
    - Authentication
    - Custom headers
    - Connection pooling
    - Concurrency limiting
```

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

### Implementing Encrypted Storage with py-hamt

Source: https://github.com/dclimate/py-hamt/blob/main/Architecture.md

This snippet shows how to set up encrypted storage using py-hamt. It generates an encryption key and then initializes a SimpleEncryptedZarrHAMTStore, demonstrating how to secure data stored within the HAMT structure.

```python
encryption_key = get_random_bytes(32)
encrypted_store = SimpleEncryptedZarrHAMTStore(
    hamt, read_only=False, encryption_key=encryption_key, header=b"app-name"
)
```

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

### Execute py-hamt tests, formatting, and linting checks

Source: https://github.com/dclimate/py-hamt/blob/main/README.md

Script to run comprehensive checks including tests with code coverage, formatting, and linting. Requires an IPFS Kubo daemon or Docker for full integration tests.

```Shell
bash run-checks.sh
```

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

### Python Zarr v3 Store Interface for HAMT

Source: https://github.com/dclimate/py-hamt/blob/main/Architecture.md

Implements the Zarr v3 Store interface, providing metadata caching for `zarr.json` files. It supports efficient directory listing operations with prefix matching, directly mapping Zarr keys to HAMT keys.

```APIDOC
ZarrHAMTStore Class (zarr_hamt_store.py:11)
  - Implements: Zarr v3 Store interface
  - Features:
    - Metadata caching (for zarr.json)
    - Directory listing (efficient prefix matching)
  - Key Mapping: Zarr keys map directly to HAMT keys
```

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

### Profile py-hamt CPU and memory usage

Source: https://github.com/dclimate/py-hamt/blob/main/README.md

Commands to generate CPU profiles using cProfile and memory profiles using memray for the test suite, and then visualize them with snakeviz and memray flamegraph.

```Shell
source .venv/bin/activate
python -m cProfile -o profile.prof -m pytest
python -m memray run -m pytest
```

```Shell
uv run snakeviz .
uv run memray flamegraph <memray output>
```

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

### Run pre-commit checks across codebase

Source: https://github.com/dclimate/py-hamt/blob/main/README.md

Command to manually run all pre-commit checks on the entire codebase.

```Shell
pre-commit run --all-files
```

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

### Integrating py-hamt with IPFS

Source: https://github.com/dclimate/py-hamt/blob/main/Architecture.md

This snippet demonstrates how to integrate the py-hamt library with IPFS using KuboCAS. It shows building a HAMT, setting a key-value pair, making the HAMT read-only, and retrieving the IPFS Content Identifier (CID) of the root node.

```python
kubo_cas = KuboCAS()
hamt = await HAMT.build(cas=kubo_cas)
await hamt.set("key", "value")
await hamt.make_read_only()
cid = hamt.root_node_id  # IPFS CID
```

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

### Python Abstract Content-Addressed Store Interface

Source: https://github.com/dclimate/py-hamt/blob/main/Architecture.md

An abstract base class defining the interface for content-addressed storage backends. It specifies methods for storing content and retrieving immutable IDs, supporting 'raw' and 'dag-cbor' codec types.

```APIDOC
ContentAddressedStore Class (store.py:11)
  - Abstract Base Class
  - Returns immutable IDs (IPLDKind)
  - Codec Types:
    - "raw" (for data)
    - "dag-cbor" (for structured content)
```

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

### Python Encrypted Zarr HAMT Store

Source: https://github.com/dclimate/py-hamt/blob/main/Architecture.md

Extends ZarrHAMTStore to provide ChaCha20-Poly1305 encryption for all data, including metadata. It uses standard 24-byte nonces and 16-byte authentication tags for secure storage.

```APIDOC
SimpleEncryptedZarrHAMTStore Class (encryption_hamt_store.py:12)
  - Extends: ZarrHAMTStore
  - Encryption: ChaCha20-Poly1305
  - Scope: Encrypts all data (including metadata)
  - Parameters:
    - Nonces: 24-byte
    - Authentication Tags: 16-byte
```

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

### Python HAMT Node Class Definition

Source: https://github.com/dclimate/py-hamt/blob/main/Architecture.md

Defines the core Node structure for the HAMT, managing 256 buckets. It handles storage of key-value mappings or links to child nodes, and serializes to DAG-CBOR for content addressing.

```APIDOC
Node Class (hamt.py:62)
  - Fixed array of 256 elements (buckets)
  - Buckets:
    - Empty: {} (empty dict)
    - Key-value mappings: dictionary (when bucket size ≤ max_bucket_size)
    - Child Node Link: [link_id] (single-element list)
  - Serialization: DAG-CBOR format
```

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

### Python In-Memory Read-Write Node Tree Store

Source: https://github.com/dclimate/py-hamt/blob/main/Architecture.md

A node storage strategy used in read-write HAMT mode. It maintains modified nodes in an in-memory buffer using temporary UUID4 integers as IDs and includes a sophisticated flush algorithm for `vacate()`.

```APIDOC
InMemoryTreeStore Class (hamt.py:180)
  - Usage: Read-write HAMT mode
  - Node Management: Maintains modified nodes in memory buffer
  - Node IDs: UUID4 integers (temporary)
  - Flush Algorithm: Sophisticated during vacate()
```

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

### Python HAMT Main Interface Class

Source: https://github.com/dclimate/py-hamt/blob/main/Architecture.md

The primary interface for Hash Array Mapped Trie operations. It supports both read-only and read-write modes, uses asyncio locks for thread safety in write mode, and abstracts node storage strategies.

```APIDOC
HAMT Class (hamt.py:287)
  - Modes:
    - Read-only
    - Read-write
  - Concurrency: asyncio locks (for write mode)
  - Node Storage: Uses NodeStore abstraction
```

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

### Python Read-Only Node Cache Store

Source: https://github.com/dclimate/py-hamt/blob/main/Architecture.md

A node storage strategy used in read-only HAMT mode. It implements LRU-style caching for loaded nodes, optimizing for concurrent read operations, and explicitly disallows write operations.

```APIDOC
ReadCacheStore Class (hamt.py:150)
  - Usage: Read-only HAMT mode
  - Caching: LRU-style for loaded nodes
  - Writes: Not supported (throws exception)
  - Optimization: Concurrent read operations
```

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