# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

### Building
- `make build`: Build the package with Cython extensions
- `make clean`: Clean build artifacts and compiled extensions
- `python setup.py build_ext`: Build Cython extensions only

### Testing
- `python -m pytest`: Run all tests (416 tests collected)
- `python -m pytest tests/test_file.py`: Run specific test file
- `python -m pytest -k "test_name"`: Run tests matching pattern
- `tox`: Run tests across multiple Python environments (flake8, py37, py38, py39, py310, py311, py312, pypy3)
- `tox -e flake8`: Run flake8 linting

### Package Management
- `pip install -e .`: Install in development mode
- `pip install -e .[dev]`: Install with development dependencies
- `pip install -e .[tornado]`: Install with tornado support

## Code Architecture

ThriftPy2 is a pure Python implementation of Apache Thrift with the following structure:

### Core Components
- **thriftpy2/thrift.py**: Main Thrift type system and struct definitions
- **thriftpy2/parser/**: Thrift file parser (lexer.py, parser.py) using PLY
- **thriftpy2/protocol/**: Protocol implementations (binary, compact, json, apache_json)
- **thriftpy2/transport/**: Transport implementations (buffered, framed, socket, ssl)
- **thriftpy2/rpc.py**: RPC client/server utilities
- **thriftpy2/server.py**: Server implementations

### Async Support
- **thriftpy2/contrib/aio/**: Asyncio support (Python 3.5+)
- **thriftpy2/tornado.py**: Tornado framework integration

### Performance Optimizations
- **thriftpy2/protocol/cybin/**: Cython-optimized binary protocol
- **thriftpy2/transport/cybase/**: Cython-optimized transport base

### Key Features
- Pure Python implementation (no Thrift compiler required)
- Load Thrift files dynamically as Python modules
- Support for multiple protocols and transports
- Async/await support via asyncio
- Tornado framework integration
- Compatible with Apache Thrift servers/clients

## Testing Structure

Tests are located in the root directory (not in a tests/ subdirectory):
- **test_*.py**: Individual test modules
- **conftest.py**: Pytest configuration
- ***.thrift**: Thrift definition files used in tests

Common test patterns:
- Protocol tests: test_protocol_*.py
- Transport tests: test_*_transport.py
- RPC tests: test_rpc.py
- Async tests: test_aio.py
- Parser tests: test_parser.py

## Development Notes

- The project uses Cython for performance-critical components
- Setup.py handles Cython extension building
- Tox is configured for multi-environment testing
- Requires Python 3.7+
- Main dependencies: anyio, ply, six
- Optional: tornado for Tornado support