tracepanel 0.0.1a1__tar.gz

tracepanel-0.0.1a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DevRealm OÜ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tracepanel-0.0.1a1/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: tracepanel
+Version: 0.0.1a1
+Summary: Traces and logs for Python apps: every request, task and command with its SQL and log lines, N+1 queries found
+Keywords: debug toolbar,django,fastapi,flask,n+1,sql,tracing,profiling
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Typing :: Typed
+Requires-Dist: tracepanel-agent==0.0.1a1 ; (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'armv6l' and sys_platform == 'linux') or (platform_machine == 'armv7l' and sys_platform == 'linux') or (platform_machine == 'i686' and sys_platform == 'linux') or (platform_machine == 'ppc64le' and sys_platform == 'linux') or (platform_machine == 'riscv64' and sys_platform == 'linux') or (platform_machine == 's390x' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux') or (platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'ARM64' and sys_platform == 'win32') or (platform_machine == 'x86' and sys_platform == 'win32') or sys_platform == 'darwin'
+Requires-Dist: celery>=5.3 ; extra == 'celery'
+Requires-Dist: channels>=4.2 ; extra == 'channels'
+Requires-Dist: django>=5.2 ; extra == 'django'
+Requires-Dist: dramatiq>=1.17 ; extra == 'dramatiq'
+Requires-Dist: djangorestframework>=3.15 ; extra == 'drf'
+Requires-Dist: falcon>=4.0 ; extra == 'falcon'
+Requires-Dist: fastapi>=0.142 ; extra == 'fastapi'
+Requires-Dist: flask>=3.0 ; extra == 'flask'
+Requires-Dist: django-ninja>=1.4 ; extra == 'ninja'
+Requires-Dist: opentelemetry-sdk>=1.45 ; extra == 'otel'
+Requires-Dist: rq>=2.0 ; extra == 'rq'
+Requires-Dist: sqlalchemy>=2.0 ; extra == 'sqlalchemy'
+Requires-Dist: starlette>=0.40 ; extra == 'starlette'
+Requires-Dist: strawberry-graphql>=0.250 ; extra == 'strawberry'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/tracepanel/tracepanel
+Project-URL: Repository, https://github.com/tracepanel/tracepanel-python
+Project-URL: Issues, https://github.com/tracepanel/tracepanel-python/issues
+Project-URL: Changelog, https://github.com/tracepanel/tracepanel-python/blob/main/CHANGELOG.md
+Provides-Extra: celery
+Provides-Extra: channels
+Provides-Extra: django
+Provides-Extra: dramatiq
+Provides-Extra: drf
+Provides-Extra: falcon
+Provides-Extra: fastapi
+Provides-Extra: flask
+Provides-Extra: ninja
+Provides-Extra: otel
+Provides-Extra: rq
+Provides-Extra: sqlalchemy
+Provides-Extra: starlette
+Provides-Extra: strawberry
+Description-Content-Type: text/markdown
+
+# Tracepanel
+
+**See what your app does on every request.** Tracepanel records each request,
+background task and command of your Python app with its SQL queries, logs and
+errors. It points out N+1 queries, duplicate queries and slow SQL, and names the
+line of code to fix. You read it in a panel on your pages and in a console.
+
+It runs while you develop, and everything stays on your machine.
+
+## Install
+
+```bash
+pip install tracepanel
+```
+
+Tracepanel is on only in development: when `DEBUG` is on, in a debug server,
+or under `tracepanel run`. Add it to your app:
+
+```python
+# Django: settings.py
+INSTALLED_APPS += ["tracepanel.django"]
+```
+
+```python
+# FastAPI
+from fastapi import FastAPI
+
+import tracepanel.fastapi
+
+app = FastAPI(debug=True)
+tracepanel.fastapi.install(app)
+```
+
+```python
+# Flask, started with `flask run --debug`
+from flask import Flask
+
+import tracepanel.flask
+
+app = Flask(__name__)
+tracepanel.flask.install(app)
+```
+
+Open a page of your app and click the badge in the corner. On a page that
+loads each post's author in its own query, the panel shows
+`SELECT auth_user ×50` marked N+1, the line of code that ran it, and the
+`select_related()` that turns 50 queries into one. The console at
+`/__tracepanel__/` holds every request, task and command the app ran.
+
+Tracepanel also traces Celery, Dramatiq, RQ, SQLAlchemy, Strawberry, Django REST
+framework, Django Ninja, Channels and htmx when they are installed. It reads the
+log lines you write with `logging` and attaches each one to the request, task
+or command that wrote it. Your logging configuration stays as it is.
+
+For Django, `pip install django-tracepanel` installs the same package.
+
+## Run without changing your code
+
+`tracepanel run` turns Tracepanel on for one command. The project stays as it
+is:
+
+```bash
+tracepanel run python manage.py runserver   # Django
+tracepanel run uvicorn app.main:app         # FastAPI, Starlette
+tracepanel run flask --app app run          # Flask
+tracepanel run gunicorn app:app             # Falcon
+tracepanel run celery -A app worker         # a worker
+```
+
+## Configure
+
+Every setting has a default. To change one, set it in one of these places, and
+a later place wins:
+
+1. `tracepanel.toml`, or `[tool.tracepanel]` in `pyproject.toml`
+2. the `TRACEPANEL` dict in Django's settings
+3. a `TRACEPANEL_<NAME>` variable, such as `TRACEPANEL_SLOW_SQL_MS=50`
+
+```toml
+# pyproject.toml
+[tool.tracepanel]
+slow_sql_ms = 50
+n_plus_one_threshold = 5
+ignore_paths = ["/health*", "/static/*"]
+```
+
+`tracepanel config` prints each setting, its value and where it comes from.
+
+## Trace your own code
+
+To add your own steps to a request or a task, or to trace a script or a
+scheduled job:
+
+```python
+import time
+
+import tracepanel
+
+
+@tracepanel.traced
+def rebuild_index() -> None:
+    with tracepanel.span("index.load", source="db") as span:
+        time.sleep(0.01)
+        span.set("rows", 120)
+    tracepanel.event("index rebuilt", rows=120)
+
+
+with tracepanel.trace("rebuild-index"):
+    tracepanel.set_attr("tenant", "acme", on_trace=True)
+    rebuild_index()
+```
+
+`span()` adds a step to the current trace, and `@traced` does the same for a
+function. `trace()` starts a new trace. Tracepanel stores keyword attributes
+under `app.`, so `source` becomes `app.source`. SQL, logs and errors inside a
+span belong to that span. Outside development these calls do nothing, so you
+can leave them in.
+
+## Command line
+
+| Command | What it does |
+| --- | --- |
+| `tracepanel run <command>` | runs a command with Tracepanel on |
+| `tracepanel dev` | runs the agent in the foreground, with the console on http://127.0.0.1:8765/ |
+| `tracepanel config` | prints the settings in effect and where each comes from |
+| `tracepanel clear` | deletes every stored trace, log, query, email and issue |
+| `tracepanel mcp` | gives an AI coding agent your traces over MCP |
+
+## Supported versions
+
+| Python | Django |
+| --- | --- |
+| 3.11 | 5.2 |
+| 3.12, 3.13, 3.14 | 5.2, 6.0, 6.1 |
+| 3.15 | 6.1 |
+
+## Links
+
+- [tracepanel](https://github.com/tracepanel/tracepanel): what Tracepanel finds,
+  how it works, privacy, and the agent this package installs
+- [CHANGELOG.md](CHANGELOG.md): what changed in each version
+- [CONTRIBUTING.md](CONTRIBUTING.md): developing this package
+
+## License
+
+Licensed under the [MIT License](LICENSE).

tracepanel-0.0.1a1/README.md

@@ -0,0 +1,146 @@
+# Tracepanel
+
+**See what your app does on every request.** Tracepanel records each request,
+background task and command of your Python app with its SQL queries, logs and
+errors. It points out N+1 queries, duplicate queries and slow SQL, and names the
+line of code to fix. You read it in a panel on your pages and in a console.
+
+It runs while you develop, and everything stays on your machine.
+
+## Install
+
+```bash
+pip install tracepanel
+```
+
+Tracepanel is on only in development: when `DEBUG` is on, in a debug server,
+or under `tracepanel run`. Add it to your app:
+
+```python
+# Django: settings.py
+INSTALLED_APPS += ["tracepanel.django"]
+```
+
+```python
+# FastAPI
+from fastapi import FastAPI
+
+import tracepanel.fastapi
+
+app = FastAPI(debug=True)
+tracepanel.fastapi.install(app)
+```
+
+```python
+# Flask, started with `flask run --debug`
+from flask import Flask
+
+import tracepanel.flask
+
+app = Flask(__name__)
+tracepanel.flask.install(app)
+```
+
+Open a page of your app and click the badge in the corner. On a page that
+loads each post's author in its own query, the panel shows
+`SELECT auth_user ×50` marked N+1, the line of code that ran it, and the
+`select_related()` that turns 50 queries into one. The console at
+`/__tracepanel__/` holds every request, task and command the app ran.
+
+Tracepanel also traces Celery, Dramatiq, RQ, SQLAlchemy, Strawberry, Django REST
+framework, Django Ninja, Channels and htmx when they are installed. It reads the
+log lines you write with `logging` and attaches each one to the request, task
+or command that wrote it. Your logging configuration stays as it is.
+
+For Django, `pip install django-tracepanel` installs the same package.
+
+## Run without changing your code
+
+`tracepanel run` turns Tracepanel on for one command. The project stays as it
+is:
+
+```bash
+tracepanel run python manage.py runserver   # Django
+tracepanel run uvicorn app.main:app         # FastAPI, Starlette
+tracepanel run flask --app app run          # Flask
+tracepanel run gunicorn app:app             # Falcon
+tracepanel run celery -A app worker         # a worker
+```
+
+## Configure
+
+Every setting has a default. To change one, set it in one of these places, and
+a later place wins:
+
+1. `tracepanel.toml`, or `[tool.tracepanel]` in `pyproject.toml`
+2. the `TRACEPANEL` dict in Django's settings
+3. a `TRACEPANEL_<NAME>` variable, such as `TRACEPANEL_SLOW_SQL_MS=50`
+
+```toml
+# pyproject.toml
+[tool.tracepanel]
+slow_sql_ms = 50
+n_plus_one_threshold = 5
+ignore_paths = ["/health*", "/static/*"]
+```
+
+`tracepanel config` prints each setting, its value and where it comes from.
+
+## Trace your own code
+
+To add your own steps to a request or a task, or to trace a script or a
+scheduled job:
+
+```python
+import time
+
+import tracepanel
+
+
+@tracepanel.traced
+def rebuild_index() -> None:
+    with tracepanel.span("index.load", source="db") as span:
+        time.sleep(0.01)
+        span.set("rows", 120)
+    tracepanel.event("index rebuilt", rows=120)
+
+
+with tracepanel.trace("rebuild-index"):
+    tracepanel.set_attr("tenant", "acme", on_trace=True)
+    rebuild_index()
+```
+
+`span()` adds a step to the current trace, and `@traced` does the same for a
+function. `trace()` starts a new trace. Tracepanel stores keyword attributes
+under `app.`, so `source` becomes `app.source`. SQL, logs and errors inside a
+span belong to that span. Outside development these calls do nothing, so you
+can leave them in.
+
+## Command line
+
+| Command | What it does |
+| --- | --- |
+| `tracepanel run <command>` | runs a command with Tracepanel on |
+| `tracepanel dev` | runs the agent in the foreground, with the console on http://127.0.0.1:8765/ |
+| `tracepanel config` | prints the settings in effect and where each comes from |
+| `tracepanel clear` | deletes every stored trace, log, query, email and issue |
+| `tracepanel mcp` | gives an AI coding agent your traces over MCP |
+
+## Supported versions
+
+| Python | Django |
+| --- | --- |
+| 3.11 | 5.2 |
+| 3.12, 3.13, 3.14 | 5.2, 6.0, 6.1 |
+| 3.15 | 6.1 |
+
+## Links
+
+- [tracepanel](https://github.com/tracepanel/tracepanel): what Tracepanel finds,
+  how it works, privacy, and the agent this package installs
+- [CHANGELOG.md](CHANGELOG.md): what changed in each version
+- [CONTRIBUTING.md](CONTRIBUTING.md): developing this package
+
+## License
+
+Licensed under the [MIT License](LICENSE).

tracepanel-0.0.1a1/pyproject.toml

@@ -0,0 +1,272 @@
+[project]
+name = "tracepanel"
+version = "0.0.1a1"
+description = "Traces and logs for Python apps: every request, task and command with its SQL and log lines, N+1 queries found"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = ['tracepanel-agent==0.0.1a1; (sys_platform == "linux" and (platform_machine == "x86_64" or platform_machine == "aarch64" or platform_machine == "armv7l" or platform_machine == "armv6l" or platform_machine == "i686" or platform_machine == "ppc64le" or platform_machine == "s390x" or platform_machine == "riscv64")) or sys_platform == "darwin" or (sys_platform == "win32" and (platform_machine == "AMD64" or platform_machine == "ARM64" or platform_machine == "x86"))']
+keywords = [
+    "debug toolbar",
+    "django",
+    "fastapi",
+    "flask",
+    "n+1",
+    "sql",
+    "tracing",
+    "profiling",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Framework :: FastAPI",
+    "Framework :: Flask",
+    "Framework :: Django",
+    "Framework :: Django :: 5.2",
+    "Framework :: Django :: 6.0",
+    "Framework :: Django :: 6.1",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Software Development :: Debuggers",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+django = ["django>=5.2"]
+celery = ["celery>=5.3"]
+dramatiq = ["dramatiq>=1.17"]
+rq = ["rq>=2.0"]
+channels = ["channels>=4.2"]
+strawberry = ["strawberry-graphql>=0.250"]
+fastapi = ["fastapi>=0.142"]
+starlette = ["starlette>=0.40"]
+flask = ["flask>=3.0"]
+falcon = ["falcon>=4.0"]
+sqlalchemy = ["sqlalchemy>=2.0"]
+ninja = ["django-ninja>=1.4"]
+drf = ["djangorestframework>=3.15"]
+otel = ["opentelemetry-sdk>=1.45"]
+
+[project.scripts]
+tracepanel = "tracepanel._cli:main"
+
+[project.urls]
+Homepage = "https://github.com/tracepanel/tracepanel"
+Repository = "https://github.com/tracepanel/tracepanel-python"
+Issues = "https://github.com/tracepanel/tracepanel-python/issues"
+Changelog = "https://github.com/tracepanel/tracepanel-python/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+celery = ["celery>=5.6.3"]
+channels = [
+    "channels>=4.3.2",
+    "daphne>=4.2.3",
+]
+dev = [
+    "django>=5.2",
+    "pytest",
+    "pytest-django",
+    "jsonschema",
+    "types-jsonschema",
+    "ruff>=0.16",
+    "pyrefly>=1.3",
+    "poethepoet>=0.48",
+    "django-stubs>=5.2",
+    "dirty-equals>=0.11",
+    "pyyaml>=6.0.3",
+    "types-pyyaml>=6.0.12.20260906",
+    "celery-types>=0.26.0",
+    "import-linter>=2.15",
+]
+django-tasks = [
+    "django-tasks>=0.12.0",
+    "django-tasks-db>=0.13.0",
+]
+postgres = ["psycopg[binary]>=3.2"]
+strawberry = ["strawberry-graphql>=0.332.0"]
+dramatiq = [
+    "dramatiq>=2.2.1",
+    "redis>=8.1.0",
+]
+rq = [
+    "rq>=2.12.0",
+    "fakeredis>=2.39.0",
+]
+fastapi = [
+    "fastapi>=0.142.4",
+    "httpx2>=2.13.1",
+    "sqlalchemy>=2.1.4",
+]
+ninja = ["django-ninja>=1.7.1"]
+drf = ["djangorestframework>=3.18.3"]
+otel = ["opentelemetry-sdk>=1.45.1"]
+flask = [
+    "flask>=3.1.3",
+    "flask-sqlalchemy>=3.1.1",
+    "sqlalchemy>=2.1.4",
+]
+falcon = ["falcon>=4.2"]
+
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.sources.tracepanel-agent]
+path = "../tracepanel"
+
+[tool.uv.build-backend]
+module-name = "tracepanel"
+module-root = ""
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",
+    "CPY",
+    "D1",
+]
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff.lint.isort]
+known-third-party = [
+    "celery",
+    "channels",
+    "strawberry",
+    "ninja",
+    "rest_framework",
+    "django",
+    "fastapi",
+    "flask",
+    "falcon",
+    "starlette",
+    "sqlalchemy",
+    "opentelemetry",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101",
+    "PLR2004",
+    "ARG001",
+    "ARG002",
+    "S105",
+    "S106",
+]
+"**/migrations/**" = ["RUF012"]
+"tracepanel/_cli.py" = ["T201"]
+"tracepanel/_bootstrap/sitecustomize.py" = ["INP001"]
+"scripts/*.py" = ["INP001"]
+"scripts/bench.py" = [
+    "INP001",
+    "T201",
+]
+"scripts/test_matrix.py" = [
+    "INP001",
+    "T201",
+]
+
+[tool.poe.tasks.build]
+help = "Build the wheel and sdist into dist/, and check what they hold"
+sequence = [
+    "uv build",
+    "python scripts/check_dist.py",
+]
+default_item_type = "cmd"
+
+[tool.poe.tasks.test-matrix]
+help = "Tests on every supported Python x Django pair, as CI runs them (scripts/test_matrix.py)"
+cmd = "python scripts/test_matrix.py"
+
+[tool.poe.tasks.bench]
+help = "Overhead per request, memory over many requests (scripts/bench.py)"
+cmd = "python scripts/bench.py"
+
+[tool.poe.tasks.test]
+help = "Run the test suite"
+cmd = "pytest"
+
+[tool.poe.tasks.fmt]
+help = "Fix lint issues and format code"
+sequence = [
+    "ruff check --fix .",
+    "ruff format .",
+]
+default_item_type = "cmd"
+
+[tool.poe.tasks.lint]
+help = "Check linting, formatting, types, imports and the docs (runs every check, fails if any fails)"
+sequence = [
+    "ruff check .",
+    "ruff format --check .",
+    "pyrefly check",
+    "lint-imports",
+    "python scripts/lint_docs.py",
+]
+default_item_type = "cmd"
+ignore_fail = "return_non_zero"
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.project.settings"
+pythonpath = ["."]
+django_debug_mode = true
+
+[tool.pyrefly]
+preset = "strict"
+python-version = "3.11"
+project-includes = [
+    "tracepanel",
+    "tests",
+    "scripts",
+]
+
+[tool.importlinter]
+root_package = "tracepanel"
+include_external_packages = true
+
+[[tool.importlinter.contracts]]
+name = "Only the framework integrations (tracepanel.django, .fastapi, .flask, .falcon) import their framework"
+type = "forbidden"
+source_modules = [
+    "tracepanel.core",
+    "tracepanel.storage",
+    "tracepanel.console",
+    "tracepanel.integrations",
+    "tracepanel.api",
+    "tracepanel.asgi",
+    "tracepanel.wsgi",
+]
+forbidden_modules = [
+    "django",
+    "channels",
+    "fastapi",
+    "starlette",
+    "flask",
+    "werkzeug",
+    "falcon",
+]
+
+[[tool.importlinter.contracts]]
+name = "Layers: the framework integration on top, the core at the bottom"
+type = "layers"
+layers = [
+    "tracepanel.django | tracepanel.fastapi | tracepanel.flask | tracepanel.falcon",
+    "tracepanel.asgi | tracepanel.wsgi",
+    "tracepanel.integrations | tracepanel.console | tracepanel.api",
+    "tracepanel.storage",
+    "tracepanel.core",
+]