From 8f2ebfb7dace58a6d0841f42f674e8234bb3e119 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Tue, 3 Mar 2026 10:58:44 +0100 Subject: [PATCH 1/7] docs: Add AGENTS.md --- AGENTS.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 64 insertions(+) create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..e73cd1df11 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,63 @@ +# Agent Instructions + +## Package Manager + +Use **tox** for testing (not pytest directly): +- Always run tox from the main `.venv`. If there is no `.venv`, create it and install `pip install -r requirements-lint.txt -r requirements-test.txt tox` +- Test matrix config is in `tox.ini` +- Integration tests: `tox -e py3.14-{integration}-v{version}` +- Common tests: `tox -e py3.14-common` + +## Type Checking + +- Always run mypy from the main `.venv`. If there is no `.venv`, create it and install `pip install -r requirements-lint.txt -r requirements-test.txt` +- Run `mypy sentry_sdk` before committing (must pass with zero errors) +- Strict mode enabled (`check_untyped_defs`, `disallow_untyped_defs`) + +## Linting & Formatting + +- **Ruff** for linting and formatting +- `ruff check tests sentry_sdk` +- `ruff format --check tests sentry_sdk` +- Full lint suite: `tox -e linters` + +## Commit Attribution + +AI commits MUST include: +``` +Co-Authored-By: +``` +Example: `Co-Authored-By: Claude Opus 4.6 ` + +## Auto-Generated Files + +Do NOT edit these directly — modify source scripts instead: +- `tox.ini` — generated by `scripts/populate_tox/populate_tox.py` from `scripts/populate_tox/tox.jinja` +- `.github/workflows/test-integrations-*.yml` — generated by `scripts/split_tox_gh_actions/split_tox_gh_actions.py` +- Regenerate all: `scripts/generate-test-files.sh` + +## Adding Integrations to Test Suite + +1. Add minimum version to `_MIN_VERSIONS` in `sentry_sdk/integrations/__init__.py` +2. Add config to `TEST_SUITE_CONFIG` in `scripts/populate_tox/config.py` +3. Add to group in `scripts/split_tox_gh_actions/split_tox_gh_actions.py` +4. Run `scripts/generate-test-files.sh` + +## Integration Contract + +- Don't crash applications or swallow exceptions +- Don't mutate object references or alter function signatures +- Don't leak file descriptors or make unexpected DB requests +- Write defensive code +- Use end-to-end tests (not mocks) + +## Key Paths + +| Path | Description | +|------|-------------| +| `sentry_sdk/integrations/` | integration modules | +| `sentry_sdk/ai/` | AI monitoring | +| `sentry_sdk/crons/` | Cron monitoring | +| `sentry_sdk/profiler/` | Performance profiling | +| `tests/integrations/{name}/` | Integration test suites | +| `scripts/populate_tox/config.py` | Test suite configuration | diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000000..47dc3e3d86 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file From 17da4de211866a44d51975de2129a0839d4678a7 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Tue, 3 Mar 2026 15:46:04 +0100 Subject: [PATCH 2/7] Add tox envs for mypy, ruff; tweak --- AGENTS.md | 18 +++++++++++------- tox.ini | 14 ++++++++++++++ 2 files changed, 25 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e73cd1df11..af6dc79406 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,25 +1,29 @@ # Agent Instructions +## Tox + +- Always run tox from the main `.venv` +- If there is no `tox.venv`, create one with `python -m venv tox.venv`, active it and run `pip install tox` + ## Package Manager Use **tox** for testing (not pytest directly): -- Always run tox from the main `.venv`. If there is no `.venv`, create it and install `pip install -r requirements-lint.txt -r requirements-test.txt tox` -- Test matrix config is in `tox.ini` +- Test matrix configuration is in `tox.ini` - Integration tests: `tox -e py3.14-{integration}-v{version}` - Common tests: `tox -e py3.14-common` ## Type Checking -- Always run mypy from the main `.venv`. If there is no `.venv`, create it and install `pip install -r requirements-lint.txt -r requirements-test.txt` -- Run `mypy sentry_sdk` before committing (must pass with zero errors) +Use **tox** for type checking (not mypy directly): +- Run `tox -e mypy` before committing (must pass with zero errors) - Strict mode enabled (`check_untyped_defs`, `disallow_untyped_defs`) ## Linting & Formatting -- **Ruff** for linting and formatting -- `ruff check tests sentry_sdk` -- `ruff format --check tests sentry_sdk` +Use **tox** for linting (not ruff directly): +- `tox -e ruff` - Full lint suite: `tox -e linters` +- Full lint suite must pass before committing ## Commit Attribution diff --git a/tox.ini b/tox.ini index 64120eaa3d..5cf4693c85 100644 --- a/tox.ini +++ b/tox.ini @@ -327,6 +327,9 @@ deps = linters: -r requirements-linting.txt linters: werkzeug<2.3.0 + ruff: -r requirements-linting.txt + mypy: -r requirements-linting.txt + # === Common === py3.8-common: hypothesis common: pytest-asyncio @@ -915,6 +918,8 @@ basepython = # Tools like ruff and mypy have options that pin the target Python # version (configured in pyproject.toml), ensuring consistent behavior. linters: python3.14 + mypy: python3.14 + ruff: python3.14 commands = {py3.7,py3.8}-boto3: pip install urllib3<2.0.0 @@ -933,3 +938,12 @@ commands = ruff format --check tests sentry_sdk mypy sentry_sdk python scripts/find_raise_from_none.py + +[testenv:mypy] +commands = + mypy sentry_sdk + +[testenv:ruff] +commands = + ruff check tests sentry_sdk + ruff format --check tests sentry_sdk From c090c881b8aafd4f112639c0a318ce28f09b64b5 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Tue, 3 Mar 2026 15:46:43 +0100 Subject: [PATCH 3/7] . --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index af6dc79406..5b976af47c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ ## Tox -- Always run tox from the main `.venv` +- Always run tox from the main `tox.venv` - If there is no `tox.venv`, create one with `python -m venv tox.venv`, active it and run `pip install tox` ## Package Manager From 7b9062e961ae3ba86613e0bcb20a69c0c71e5fc8 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Wed, 4 Mar 2026 08:22:12 +0100 Subject: [PATCH 4/7] add to template --- scripts/populate_tox/tox.jinja | 14 ++++++++++++++ tox.ini | 2 +- 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/scripts/populate_tox/tox.jinja b/scripts/populate_tox/tox.jinja index e623c43e89..88ca79421c 100755 --- a/scripts/populate_tox/tox.jinja +++ b/scripts/populate_tox/tox.jinja @@ -76,6 +76,9 @@ deps = linters: -r requirements-linting.txt linters: werkzeug<2.3.0 + mypy: -r requirements-linting.txt + ruff: -r requirements-linting.txt + # === Common === py3.8-common: hypothesis common: pytest-asyncio @@ -212,6 +215,8 @@ basepython = # Tools like ruff and mypy have options that pin the target Python # version (configured in pyproject.toml), ensuring consistent behavior. linters: python3.14 + mypy: python3.14 + ruff: python3.14 commands = {py3.7,py3.8}-boto3: pip install urllib3<2.0.0 @@ -230,3 +235,12 @@ commands = ruff format --check tests sentry_sdk mypy sentry_sdk python scripts/find_raise_from_none.py + +[testenv:mypy] +commands = + mypy sentry_sdk + +[testenv:ruff] +commands = + ruff check tests sentry_sdk + ruff format --check tests sentry_sdk diff --git a/tox.ini b/tox.ini index 5cf4693c85..944a686a4a 100644 --- a/tox.ini +++ b/tox.ini @@ -327,8 +327,8 @@ deps = linters: -r requirements-linting.txt linters: werkzeug<2.3.0 - ruff: -r requirements-linting.txt mypy: -r requirements-linting.txt + ruff: -r requirements-linting.txt # === Common === py3.8-common: hypothesis From 7919746de2af1abe2d8d8e751054c278ac53b2fd Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Wed, 4 Mar 2026 08:23:21 +0100 Subject: [PATCH 5/7] werkzeug --- scripts/populate_tox/tox.jinja | 1 + tox.ini | 1 + 2 files changed, 2 insertions(+) diff --git a/scripts/populate_tox/tox.jinja b/scripts/populate_tox/tox.jinja index 88ca79421c..1808a7c521 100755 --- a/scripts/populate_tox/tox.jinja +++ b/scripts/populate_tox/tox.jinja @@ -77,6 +77,7 @@ deps = linters: werkzeug<2.3.0 mypy: -r requirements-linting.txt + mypy: werkzeug<2.3.0 ruff: -r requirements-linting.txt # === Common === diff --git a/tox.ini b/tox.ini index 944a686a4a..7be1a30eec 100644 --- a/tox.ini +++ b/tox.ini @@ -328,6 +328,7 @@ deps = linters: werkzeug<2.3.0 mypy: -r requirements-linting.txt + mypy: werkzeug<2.3.0 ruff: -r requirements-linting.txt # === Common === From ec058c28799dd23befc5f859361360374ba2f2b8 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Wed, 4 Mar 2026 08:33:38 +0100 Subject: [PATCH 6/7] typo --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 5b976af47c..6179106348 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,7 +3,7 @@ ## Tox - Always run tox from the main `tox.venv` -- If there is no `tox.venv`, create one with `python -m venv tox.venv`, active it and run `pip install tox` +- If there is no `tox.venv`, create one with `python -m venv tox.venv`, activate it and run `pip install tox` ## Package Manager From 048950b044a57d49363b74d05c359b0a333ad7bc Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Wed, 4 Mar 2026 08:34:30 +0100 Subject: [PATCH 7/7] Remove .cursor --- .cursor/rules/core-architecture.mdc | 122 --------------------- .cursor/rules/integrations-guide.mdc | 158 --------------------------- .cursor/rules/project-overview.mdc | 47 -------- .cursor/rules/quick-reference.mdc | 51 --------- .cursor/rules/testing-guide.mdc | 93 ---------------- 5 files changed, 471 deletions(-) delete mode 100644 .cursor/rules/core-architecture.mdc delete mode 100644 .cursor/rules/integrations-guide.mdc delete mode 100644 .cursor/rules/project-overview.mdc delete mode 100644 .cursor/rules/quick-reference.mdc delete mode 100644 .cursor/rules/testing-guide.mdc diff --git a/.cursor/rules/core-architecture.mdc b/.cursor/rules/core-architecture.mdc deleted file mode 100644 index 0af65f4815..0000000000 --- a/.cursor/rules/core-architecture.mdc +++ /dev/null @@ -1,122 +0,0 @@ ---- -description: -globs: -alwaysApply: false ---- -# Core Architecture - -## Scope and Client Pattern - -The Sentry SDK uses a **Scope and Client** pattern for managing state and context: - -### Scope -- [sentry_sdk/scope.py](mdc:sentry_sdk/scope.py) - Holds contextual data -- Holds a reference to the Client -- Contains tags, extra data, user info, breadcrumbs -- Thread-local storage for isolation - -### Client -- [sentry_sdk/client.py](mdc:sentry_sdk/client.py) - Handles event processing -- Manages transport and event serialization -- Applies sampling and filtering - -## Key Components - -### API Layer -- [sentry_sdk/api.py](mdc:sentry_sdk/api.py) - Public API functions -- `init()` - Initialize the SDK -- `capture_exception()` - Capture exceptions -- `capture_message()` - Capture custom messages -- `set_tag()`, `set_user()`, `set_context()` - Add context -- `start_transaction()` - Performance monitoring - -### Transport -- [sentry_sdk/transport.py](mdc:sentry_sdk/transport.py) - Event delivery -- `HttpTransport` - HTTP transport to Sentry servers -- Handles retries, rate limiting, and queuing - -### Integrations System -- [sentry_sdk/integrations/__init__.py](mdc:sentry_sdk/integrations/__init__.py) - Integration registry -- Base `Integration` class for all integrations -- Automatic setup and teardown -- Integration-specific configuration - -## Data Flow - -### Event Capture Flow -1. **Exception occurs** or **manual capture** called -2. **get_current_scope** gets the active current scope -2. **get_isolation_scope** gets the active isolation scope -3. **Scope data** (tags, user, context) is attached -4. **Client.process_event()** processes the event -5. **Sampling** and **filtering** applied -6. **Transport** sends to Sentry servers - -### Performance Monitoring Flow -1. **Transaction started** with `start_transaction()` -2. **Spans** created for operations within transaction with `start_span()` -3. **Timing data** collected automatically -4. **Transaction finished** and sent to Sentry - -## Context Management - -### Scope Stack -- **Global scope**: Default scope for the process -- **Isolation scope**: Isolated scope for specific operations, manages concurrency isolation -- **Current scope**: Active scope for current execution context - -### Scope Operations -- `configure_scope()` - Modify current scope -- `new_scope()` - Create isolated scope - -## Integration Architecture - -### Integration Lifecycle -1. **Registration**: Integration registered during `init()` -2. **Setup**: `setup_once()` called to install hooks -3. **Runtime**: Integration monitors and captures events -4. **Teardown**: Integration cleaned up on shutdown - -### Common Integration Patterns -- **Monkey patching**: Replace functions/methods with instrumented versions -- **Signal handlers**: Hook into framework signals/events -- **Middleware**: Add middleware to web frameworks -- **Exception handlers**: Catch and process exceptions - -### Integration Configuration -```python -# Example integration setup -sentry_sdk.init( - dsn="your-dsn", - integrations=[ - DjangoIntegration(), - CeleryIntegration(), - RedisIntegration(), - ], - traces_sample_rate=1.0, -) -``` - -## Error Handling - -### Exception Processing -- **Automatic capture**: Unhandled exceptions captured automatically -- **Manual capture**: Use `capture_exception()` for handled exceptions -- **Context preservation**: Stack traces, local variables, and context preserved - -### Breadcrumbs -- **Automatic breadcrumbs**: Framework operations logged automatically -- **Manual breadcrumbs**: Use `add_breadcrumb()` for custom events -- **Breadcrumb categories**: HTTP, database, navigation, etc. - -## Performance Monitoring - -### Transaction Tracking -- **Automatic transactions**: Web requests, background tasks -- **Custom transactions**: Use `start_transaction()` for custom operations -- **Span tracking**: Database queries, HTTP requests, custom operations -- **Performance data**: Timing, resource usage, custom measurements - -### Sampling -- **Transaction sampling**: Control percentage of transactions captured -- **Dynamic sampling**: Adjust sampling based on context diff --git a/.cursor/rules/integrations-guide.mdc b/.cursor/rules/integrations-guide.mdc deleted file mode 100644 index 6785b1522d..0000000000 --- a/.cursor/rules/integrations-guide.mdc +++ /dev/null @@ -1,158 +0,0 @@ ---- -description: -globs: -alwaysApply: false ---- -# Integrations Guide - -## Integration Categories - -The Sentry Python SDK includes integrations for popular frameworks, libraries, and services: - -### Web Frameworks -- [sentry_sdk/integrations/django/](mdc:sentry_sdk/integrations/django) - Django web framework -- [sentry_sdk/integrations/flask/](mdc:sentry_sdk/integrations/flask) - Flask microframework -- [sentry_sdk/integrations/fastapi/](mdc:sentry_sdk/integrations/fastapi) - FastAPI framework -- [sentry_sdk/integrations/starlette/](mdc:sentry_sdk/integrations/starlette) - Starlette ASGI framework -- [sentry_sdk/integrations/sanic/](mdc:sentry_sdk/integrations/sanic) - Sanic async framework -- [sentry_sdk/integrations/tornado/](mdc:sentry_sdk/integrations/tornado) - Tornado web framework -- [sentry_sdk/integrations/pyramid/](mdc:sentry_sdk/integrations/pyramid) - Pyramid framework -- [sentry_sdk/integrations/bottle/](mdc:sentry_sdk/integrations/bottle) - Bottle microframework -- [sentry_sdk/integrations/chalice/](mdc:sentry_sdk/integrations/chalice) - AWS Chalice -- [sentry_sdk/integrations/quart/](mdc:sentry_sdk/integrations/quart) - Quart async framework -- [sentry_sdk/integrations/falcon/](mdc:sentry_sdk/integrations/falcon) - Falcon framework -- [sentry_sdk/integrations/litestar/](mdc:sentry_sdk/integrations/litestar) - Litestar framework -- [sentry_sdk/integrations/starlite/](mdc:sentry_sdk/integrations/starlite) - Starlite framework - -### Task Queues and Background Jobs -- [sentry_sdk/integrations/celery/](mdc:sentry_sdk/integrations/celery) - Celery task queue -- [sentry_sdk/integrations/rq/](mdc:sentry_sdk/integrations/rq) - Redis Queue -- [sentry_sdk/integrations/huey/](mdc:sentry_sdk/integrations/huey) - Huey task queue -- [sentry_sdk/integrations/arq/](mdc:sentry_sdk/integrations/arq) - Arq async task queue -- [sentry_sdk/integrations/dramatiq/](mdc:sentry_sdk/integrations/dramatiq) - Dramatiq task queue - -### Databases and Data Stores -- [sentry_sdk/integrations/sqlalchemy/](mdc:sentry_sdk/integrations/sqlalchemy) - SQLAlchemy ORM -- [sentry_sdk/integrations/asyncpg/](mdc:sentry_sdk/integrations/asyncpg) - AsyncPG PostgreSQL -- [sentry_sdk/integrations/pymongo/](mdc:sentry_sdk/integrations/pymongo) - PyMongo MongoDB -- [sentry_sdk/integrations/redis/](mdc:sentry_sdk/integrations/redis) - Redis client -- [sentry_sdk/integrations/clickhouse_driver/](mdc:sentry_sdk/integrations/clickhouse_driver) - ClickHouse driver - -### Cloud and Serverless -- [sentry_sdk/integrations/aws_lambda/](mdc:sentry_sdk/integrations/aws_lambda) - AWS Lambda -- [sentry_sdk/integrations/gcp/](mdc:sentry_sdk/integrations/gcp) - Google Cloud Platform -- [sentry_sdk/integrations/serverless/](mdc:sentry_sdk/integrations/serverless) - Serverless framework - -### HTTP and Networking -- [sentry_sdk/integrations/requests/](mdc:sentry_sdk/integrations/requests) - Requests HTTP library -- [sentry_sdk/integrations/httpx/](mdc:sentry_sdk/integrations/httpx) - HTTPX async HTTP client -- [sentry_sdk/integrations/aiohttp/](mdc:sentry_sdk/integrations/aiohttp) - aiohttp async HTTP -- [sentry_sdk/integrations/grpc/](mdc:sentry_sdk/integrations/grpc) - gRPC framework - -### AI and Machine Learning -- [sentry_sdk/integrations/openai/](mdc:sentry_sdk/integrations/openai) - OpenAI API -- [sentry_sdk/integrations/anthropic/](mdc:sentry_sdk/integrations/anthropic) - Anthropic Claude -- [sentry_sdk/integrations/cohere/](mdc:sentry_sdk/integrations/cohere) - Cohere AI -- [sentry_sdk/integrations/huggingface_hub/](mdc:sentry_sdk/integrations/huggingface_hub) - Hugging Face Hub -- [sentry_sdk/integrations/langchain/](mdc:sentry_sdk/integrations/langchain) - LangChain framework - -### GraphQL -- [sentry_sdk/integrations/graphene/](mdc:sentry_sdk/integrations/graphene) - Graphene GraphQL -- [sentry_sdk/integrations/ariadne/](mdc:sentry_sdk/integrations/ariadne) - Ariadne GraphQL -- [sentry_sdk/integrations/strawberry/](mdc:sentry_sdk/integrations/strawberry) - Strawberry GraphQL -- [sentry_sdk/integrations/gql/](mdc:sentry_sdk/integrations/gql) - GQL GraphQL client - -### Feature Flags and Configuration -- [sentry_sdk/integrations/launchdarkly/](mdc:sentry_sdk/integrations/launchdarkly) - LaunchDarkly -- [sentry_sdk/integrations/unleash/](mdc:sentry_sdk/integrations/unleash) - Unleash -- [sentry_sdk/integrations/statsig/](mdc:sentry_sdk/integrations/statsig) - Statsig -- [sentry_sdk/integrations/openfeature/](mdc:sentry_sdk/integrations/openfeature) - OpenFeature - -### Other Integrations -- [sentry_sdk/integrations/logging/](mdc:sentry_sdk/integrations/logging) - Python logging -- [sentry_sdk/integrations/loguru/](mdc:sentry_sdk/integrations/loguru) - Loguru logging -- [sentry_sdk/integrations/opentelemetry/](mdc:sentry_sdk/integrations/opentelemetry) - OpenTelemetry -- [sentry_sdk/integrations/ray/](mdc:sentry_sdk/integrations/ray) - Ray distributed computing -- [sentry_sdk/integrations/spark/](mdc:sentry_sdk/integrations/spark) - Apache Spark -- [sentry_sdk/integrations/beam/](mdc:sentry_sdk/integrations/beam) - Apache Beam - -## Integration Usage - -### Basic Integration Setup -```python -import sentry_sdk -from sentry_sdk.integrations.django import DjangoIntegration -from sentry_sdk.integrations.celery import CeleryIntegration - -sentry_sdk.init( - dsn="your-dsn", - integrations=[ - DjangoIntegration(), - CeleryIntegration(), - ], - traces_sample_rate=1.0, -) -``` - -### Integration Configuration -Most integrations accept configuration parameters: -```python -from sentry_sdk.integrations.django import DjangoIntegration -from sentry_sdk.integrations.redis import RedisIntegration - -sentry_sdk.init( - dsn="your-dsn", - integrations=[ - DjangoIntegration( - transaction_style="url", # Customize transaction naming - ), - RedisIntegration( - cache_prefixes=["myapp:"], # Filter cache operations - ), - ], -) -``` - -### Integration Testing -Each integration has corresponding tests in [tests/integrations/](mdc:tests/integrations): -- [tests/integrations/django/](mdc:tests/integrations/django) - Django integration tests -- [tests/integrations/flask/](mdc:tests/integrations/flask) - Flask integration tests -- [tests/integrations/celery/](mdc:tests/integrations/celery) - Celery integration tests - -## Integration Development - -### Creating New Integrations -1. **Create integration file** in [sentry_sdk/integrations/](mdc:sentry_sdk/integrations) -2. **Inherit from Integration base class** -3. **Implement setup_once() method** -4. **Add to integration registry** - -### Integration Base Class -```python -from sentry_sdk.integrations import Integration - -class MyIntegration(Integration): - identifier = "my_integration" - - def __init__(self, param=None): - self.param = param - - @staticmethod - def setup_once(): - # Install hooks, monkey patches, etc. - pass -``` - -### Common Integration Patterns -- **Monkey patching**: Replace functions with instrumented versions -- **Middleware**: Add middleware to web frameworks -- **Signal handlers**: Hook into framework signals -- **Exception handlers**: Catch and process exceptions -- **Context managers**: Add context to operations - -### Integration Best Practices -- **Zero configuration**: Work without user setup -- **Check integration status**: Use `sentry_sdk.get_client().get_integration()` -- **No side effects**: Don't alter library behavior -- **Graceful degradation**: Handle missing dependencies -- **Comprehensive testing**: Test all integration features diff --git a/.cursor/rules/project-overview.mdc b/.cursor/rules/project-overview.mdc deleted file mode 100644 index c8c0cf77b9..0000000000 --- a/.cursor/rules/project-overview.mdc +++ /dev/null @@ -1,47 +0,0 @@ ---- -description: -globs: -alwaysApply: false ---- -# Sentry Python SDK - Project Overview - -## What is this project? - -The Sentry Python SDK is the official Python SDK for [Sentry](mdc:https://sentry.io), an error monitoring and performance monitoring platform. It helps developers capture errors, exceptions, traces and profiles from Python applications. - -## Key Files and Directories - -### Core SDK -- [sentry_sdk/__init__.py](mdc:sentry_sdk/__init__.py) - Main entry point, exports all public APIs -- [sentry_sdk/api.py](mdc:sentry_sdk/api.py) - Public API functions (init, capture_exception, etc.) -- [sentry_sdk/client.py](mdc:sentry_sdk/client.py) - Core client implementation -- [sentry_sdk/scope.py](mdc:sentry_sdk/scope.py) - Scope holds contextual metadata such as tags that are applied automatically to events and envelopes -- [sentry_sdk/transport.py](mdc:sentry_sdk/transport.py) - HTTP Transport that sends the envelopes to Sentry's servers -- [sentry_sdk/worker.py](mdc:sentry_sdk/worker.py) - Background threaded worker with a queue to manage transport requests -- [sentry_sdk/serializer.py](mdc:sentry_sdk/serializer.py) - Serializes the payload along with truncation logic - -### Integrations -- [sentry_sdk/integrations/](mdc:sentry_sdk/integrations) - Framework and library integrations - - [sentry_sdk/integrations/__init__.py](mdc:sentry_sdk/integrations/__init__.py) - Integration registry - - [sentry_sdk/integrations/django/](mdc:sentry_sdk/integrations/django) - Django framework integration - - [sentry_sdk/integrations/flask/](mdc:sentry_sdk/integrations/flask) - Flask framework integration - - [sentry_sdk/integrations/fastapi/](mdc:sentry_sdk/integrations/fastapi) - FastAPI integration - - [sentry_sdk/integrations/celery/](mdc:sentry_sdk/integrations/celery) - Celery task queue integration - - [sentry_sdk/integrations/aws_lambda/](mdc:sentry_sdk/integrations/aws_lambda) - AWS Lambda integration - -### Configuration and Setup -- [setup.py](mdc:setup.py) - Package configuration and dependencies -- [pyproject.toml](mdc:pyproject.toml) - Modern Python project configuration -- [tox.ini](mdc:tox.ini) - Test matrix configuration for multiple Python versions and integrations -- [requirements-*.txt](mdc:requirements-testing.txt) - Various dependency requirements - -### Documentation and Guides -- [README.md](mdc:README.md) - Project overview and quick start -- [CONTRIBUTING.md](mdc:CONTRIBUTING.md) - Development and contribution guidelines -- [MIGRATION_GUIDE.md](mdc:MIGRATION_GUIDE.md) - Migration from older versions -- [CHANGELOG.md](mdc:CHANGELOG.md) - Version history and changes - -### Testing -- [tests/](mdc:tests) - Comprehensive test suite - - [tests/integrations/](mdc:tests/integrations) - Integration-specific tests - - [tests/conftest.py](mdc:tests/conftest.py) - Pytest configuration and fixtures diff --git a/.cursor/rules/quick-reference.mdc b/.cursor/rules/quick-reference.mdc deleted file mode 100644 index ef90c22f78..0000000000 --- a/.cursor/rules/quick-reference.mdc +++ /dev/null @@ -1,51 +0,0 @@ ---- -description: -globs: -alwaysApply: false ---- -# Quick Reference - -## Common Commands - -### Development Setup -```bash -make .venv -source .venv/bin/activate # Windows: .venv\Scripts\activate -``` - -### Testing - -Our test matrix is implemented in [tox](mdc:https://tox.wiki). -The following runs the whole test suite and takes a long time. - -```bash -source .venv/bin/activate -tox -``` - -Prefer testing a single environment instead while developing. - -```bash -tox -e py3.12-common -``` - -For running a single test, use the pattern: - -```bash -tox -e py3.12-common -- project/tests/test_file.py::TestClassName::test_method -``` - -For testing specific integrations, refer to the test matrix in [sentry_sdk/tox.ini](mdc:sentry_sdk/tox.ini) for finding an entry. -For example, to test django, use: - -```bash -tox -e py3.12-django-v5.2.3 -``` - -### Code Quality - -Our `linters` tox environment runs `ruff-format` for formatting, `ruff-check` for linting and `mypy` for type checking. - -```bash -tox -e linters -``` diff --git a/.cursor/rules/testing-guide.mdc b/.cursor/rules/testing-guide.mdc deleted file mode 100644 index 939f1a095b..0000000000 --- a/.cursor/rules/testing-guide.mdc +++ /dev/null @@ -1,93 +0,0 @@ ---- -description: -globs: -alwaysApply: false ---- -# Testing Guide - -## Test Structure - -### Test Organization -- [tests/](mdc:tests) - Main test directory -- [tests/conftest.py](mdc:tests/conftest.py) - Shared pytest fixtures and configuration -- [tests/integrations/](mdc:tests/integrations) - Integration-specific tests -- [tests/tracing/](mdc:tests/tracing) - Performance monitoring tests -- [tests/utils/](mdc:tests/utils) - Utility and helper tests - -### Integration Test Structure -Each integration has its own test directory: -- [tests/integrations/django/](mdc:tests/integrations/django) - Django integration tests -- [tests/integrations/flask/](mdc:tests/integrations/flask) - Flask integration tests -- [tests/integrations/celery/](mdc:tests/integrations/celery) - Celery integration tests -- [tests/integrations/aws_lambda/](mdc:tests/integrations/aws_lambda) - AWS Lambda tests - -## Running Tests - -### Tox Testing Matrix - -The [tox.ini](mdc:tox.ini) file defines comprehensive test environments. -Always run tests via `tox` from the main `.venv`. - -```bash -source .venv/bin/activate - -# Run all tox environments, takes a long time -tox - -# Run specific environment -tox -e py3.11-django-v4.2 - -# Run environments for specific Python version -tox -e py3.11-* - -# Run environments for specific integration -tox -e *-django-* - -# Run a single test -tox -e py3.12-common -- project/tests/test_file.py::TestClassName::test_method -``` - -### Test Environment Categories -- **Common tests**: `{py3.6,py3.7,py3.8,py3.9,py3.10,py3.11,py3.12,py3.13}-common` -- **Integration tests**: `{python_version}-{integration}-v{framework_version}` -- **Gevent tests**: `{py3.6,py3.8,py3.10,py3.11,py3.12}-gevent` - -## Writing Tests - -### Test File Structure -```python -import pytest -import sentry_sdk -from sentry_sdk.integrations.flask import FlaskIntegration - -def test_flask_integration(sentry_init, capture_events): - """Test Flask integration captures exceptions.""" - # Test setup - sentry_init(integrations=[FlaskIntegration()]) - events = capture_events() - - # Test execution - # ... test code ... - - # Assertions - assert len(events) == 1 - assert events[0]["exception"]["values"][0]["type"] == "ValueError" -``` - -### Common Test Patterns - -## Test Best Practices - -### Test Organization -- **One test per function**: Each test should verify one specific behavior -- **Descriptive names**: Use clear, descriptive test function names -- **Arrange-Act-Assert**: Structure tests with setup, execution, and verification -- **Isolation**: Each test should be independent and not affect others -- **No mocking**: Never use mocks in tests -- **Cleanup**: Ensure tests clean up after themselves - -## Fixtures -The most important fixtures for testing are: -- `sentry_init`: Use in the beginning of a test to simulate initializing the SDK -- `capture_events`: Intercept the events for testing event payload -- `capture_envelopes`: Intercept the envelopes for testing envelope headers and payload