Skip to content

Commit 3b33b5b

Browse files
jaredmixpaneljaredmixpanel
authored
add CLAUDE.md and copilot-instructions.md (#149)
1 parent fcc255b commit 3b33b5b

File tree

2 files changed

+213
-0
lines changed

2 files changed

+213
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Copilot Instructions for Mixpanel Python SDK
2+
3+
## Project Overview
4+
This is the official Mixpanel Python library for server-side analytics integration. It provides event tracking, user profile updates, group analytics, and feature flags with both synchronous and asynchronous support.
5+
6+
## Core Architecture
7+
8+
### Main Components
9+
- **Mixpanel class** (`mixpanel/__init__.py`): Primary entry point supporting both sync/async operations
10+
- **Consumer pattern**: `Consumer` (immediate) vs `BufferedConsumer` (batched, default 50 messages)
11+
- **Feature Flags**: Local (client-side evaluation) vs Remote (server-side) providers in `mixpanel/flags/`
12+
- **Dual sync/async API**: Most flag operations have both variants (e.g., `get_variant`/`aget_variant`)
13+
14+
### Key Design Patterns
15+
```python
16+
# Context manager pattern for resource cleanup
17+
async with Mixpanel(token, local_flags_config=config) as mp:
18+
await mp.local_flags.astart_polling_for_definitions()
19+
20+
# Consumer customization for delivery behavior
21+
mp = Mixpanel(token, consumer=BufferedConsumer())
22+
23+
# Custom serialization via DatetimeSerializer
24+
mp = Mixpanel(token, serializer=CustomSerializer)
25+
```
26+
27+
## Development Workflows
28+
29+
### Testing
30+
- **Run tests**: `pytest` (current Python) or `python -m tox` (all supported versions 3.9-3.13)
31+
- **Async testing**: Uses `pytest-asyncio` with `asyncio_mode = "auto"` in pyproject.toml
32+
- **HTTP mocking**: `responses` library for sync code, `respx` for async code
33+
- **Test structure**: `test_*.py` files in root and package directories
34+
35+
### Building & Publishing
36+
```bash
37+
pip install -e .[test,dev] # Development setup
38+
python -m build # Build distributions
39+
python -m twine upload dist/* # Publish to PyPI
40+
```
41+
42+
## Important Conventions
43+
44+
### API Endpoints & Authentication
45+
- Default endpoint: `api.mixpanel.com` (override via `api_host` parameter)
46+
- **API secret** (not key) required for `import` and `merge` endpoints
47+
- Feature flags use `/decide` endpoint; events use `/track`
48+
49+
### Error Handling & Retries
50+
- All consumers use urllib3.Retry with exponential backoff (default 4 retries)
51+
- `MixpanelException` for domain-specific errors
52+
- Feature flag operations degrade gracefully with fallback values
53+
54+
### Version & Dependencies Management
55+
- Version defined in `mixpanel/__init__.py` as `__version__`
56+
- Uses Pydantic v2+ for data validation (`mixpanel/flags/types.py`)
57+
- json-logic library for runtime flag evaluation rules
58+
59+
## Feature Flag Specifics
60+
61+
### Local Flags (Client-side evaluation)
62+
- Require explicit polling: `start_polling_for_definitions()` or context manager
63+
- Default 60s polling interval, configurable via `LocalFlagsConfig`
64+
- Runtime evaluation using json-logic for dynamic targeting
65+
66+
### Remote Flags (Server-side evaluation)
67+
- Each evaluation makes API call to Mixpanel
68+
- Better for sensitive targeting logic
69+
- Configure via `RemoteFlagsConfig`
70+
71+
### Flag Configuration Pattern
72+
```python
73+
local_config = mixpanel.LocalFlagsConfig(
74+
api_host="api-eu.mixpanel.com", # EU data residency
75+
enable_polling=True,
76+
polling_interval_in_seconds=90
77+
)
78+
mp = Mixpanel(token, local_flags_config=local_config)
79+
```
80+
81+
## Testing Patterns
82+
- Mock HTTP with `responses.activate` decorator for sync tests
83+
- Use `respx.mock` for async HTTP testing
84+
- Test consumer behavior via `LogConsumer` pattern (see `test_mixpanel.py`)
85+
- Always test both sync and async variants of flag operations
86+
87+
## Critical Implementation Notes
88+
- `alias()` method always uses synchronous Consumer regardless of main consumer type
89+
- Local flags require explicit startup; use context managers for proper cleanup
90+
- DateTime serialization handled by `DatetimeSerializer` class
91+
- All flag providers support custom API endpoints for data residency requirements

‎CLAUDE.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
This is the official Mixpanel Python library for server-side integration. It provides event tracking, user profile updates, group analytics, and feature flags functionality. The library supports both synchronous and asynchronous operations.
8+
9+
## Development Commands
10+
11+
### Environment Setup
12+
```bash
13+
# Install development and test dependencies
14+
pip install -e .[test,dev]
15+
```
16+
17+
### Testing
18+
```bash
19+
# Run all tests across all Python versions (3.9-3.13, PyPy)
20+
python -m tox
21+
22+
# Run tests for current Python version only
23+
pytest
24+
25+
# Run with coverage
26+
python -m coverage run -m pytest
27+
python -m coverage report -m
28+
python -m coverage html
29+
30+
# Run specific test file
31+
pytest test_mixpanel.py
32+
pytest mixpanel/flags/test_local_feature_flags.py
33+
```
34+
35+
### Building and Publishing
36+
```bash
37+
# Build distribution packages
38+
python -m build
39+
40+
# Publish to PyPI
41+
python -m twine upload dist/*
42+
```
43+
44+
### Documentation
45+
```bash
46+
# Build documentation
47+
python -m sphinx -b html docs docs/_build/html
48+
49+
# Publish docs to GitHub Pages
50+
python -m ghp_import -n -p docs/_build/html
51+
```
52+
53+
## Architecture
54+
55+
### Core Components
56+
57+
**Mixpanel Class** (`mixpanel/__init__.py`)
58+
- Main entry point for all tracking operations
59+
- Supports context managers (both sync and async)
60+
- Integrates with Consumer classes for message delivery
61+
- Optional feature flags providers (local and remote)
62+
63+
**Consumers**
64+
- `Consumer`: Sends HTTP requests immediately (one per call)
65+
- `BufferedConsumer`: Batches messages (default max 50) before sending
66+
- Both support retry logic (default 4 retries with exponential backoff)
67+
- All consumers support custom API endpoints via `api_host` parameter
68+
69+
**Feature Flags** (`mixpanel/flags/`)
70+
- `LocalFeatureFlagsProvider`: Client-side evaluation with polling (default 60s interval)
71+
- `RemoteFeatureFlagsProvider`: Server-side evaluation via API calls
72+
- Both providers support async operations
73+
- Types defined in `mixpanel/flags/types.py` using Pydantic models
74+
75+
### Key Design Patterns
76+
77+
1. **Dual Sync/Async Support**: Most feature flag operations have both sync and async variants (e.g., `get_variant` / `aget_variant`)
78+
79+
2. **Consumer Pattern**: Events/updates are sent via consumer objects, allowing customization of delivery behavior without changing tracking code
80+
81+
3. **Context Managers**: The Mixpanel class supports both `with` and `async with` patterns to manage flag provider lifecycle
82+
83+
4. **JSON Serialization**: Custom `DatetimeSerializer` handles datetime objects; extensible via `serializer` parameter
84+
85+
5. **Runtime Rules Engine**: Local flags support runtime evaluation using json-logic library for dynamic targeting
86+
87+
## Testing Patterns
88+
89+
- Tests use `pytest` with `pytest-asyncio` for async support
90+
- `responses` library mocks HTTP requests for sync code
91+
- `respx` library mocks HTTP requests for async code
92+
- Test files follow pattern: `test_*.py` in root or within package directories
93+
- Pytest config: `asyncio_mode = "auto"` in pyproject.toml
94+
95+
## Dependencies
96+
97+
- `requests>=2.4.2, <3`: HTTP client (sync)
98+
- `httpx>=0.27.0`: HTTP client (async)
99+
- `pydantic>=2.0.0`: Data validation and types
100+
- `asgiref>=3.0.0`: Async utilities
101+
- `json-logic>=0.7.0a0`: Runtime rules evaluation
102+
103+
## Version Management
104+
105+
Version is defined in `mixpanel/__init__.py` as `__version__` and dynamically loaded by setuptools.
106+
107+
## API Endpoints
108+
109+
Default: `api.mixpanel.com`
110+
- Events: `/track`
111+
- People: `/engage`
112+
- Groups: `/groups`
113+
- Imports: `/import`
114+
- Feature Flags: `/decide`
115+
116+
## Important Notes
117+
118+
- API secret (not API key) is required for `import` and `merge` endpoints
119+
- `alias()` always uses synchronous Consumer regardless of main consumer type
120+
- Feature flags require opt-in via constructor config parameters
121+
- Local flags poll for updates; call `start_polling_for_definitions()` or use context manager
122+
- Retry logic uses urllib3.Retry with exponential backoff

0 commit comments

Comments
 (0)