django-probe 0.1.0__tar.gz

django_probe-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.tox/
+db.sqlite3
+.env
+/site/

django_probe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Django Probe contributors
+
+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.

django_probe-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: django-probe
+Version: 0.1.0
+Summary: Count Django code patterns in a project and report the counts.
+Project-URL: Repository, https://github.com/django-probe/django-probe
+Author: Django Probe contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: AST,Django,metrics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Implementation :: CPython
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Django Probe
+
+It's hard to remove features in open-source software. [Deprecation warnings exist, but people tend to ignore them](https://sethmlarson.dev/deprecations-via-warnings-dont-work-for-python-libraries). What maintainers want to know is how many people are using a feature. That's where Django Probe comes in.
+
+Django Probe allows you to share how your project uses Django. This package counts how often specific code patterns appear in your Django project and shares the aggregated information with the community.
+
+By sharing what your project uses, you help support the Django community. This allows maintainers to know what features and APIs are actually being used, removing guess work.
+
+## Quickstart
+
+```console
+$ pip install django-probe
+$ django-probe scan .                    # inspect the payload
+$ django-probe submit .                  # send it, anonymously
+```
+
+No account is required. See [Getting started](https://docs.djangoprobe.org/getting-started/)
+for project keys, and [Privacy](https://docs.djangoprobe.org/privacy/)
+for exactly what a payload contains.
+
+### Reporting automatically
+
+You should avoid reporting this manually. The project key can be set as an environment
+variable (`DJANGO_PROBE_PROJECT_KEY`), so it drops straight into a scheduled GitHub
+Action as a repository secret. See
+[Getting started](https://docs.djangoprobe.org/getting-started/#reporting-on-a-schedule)
+for a workflow you can copy.
+
+## What we're looking to learn
+
+This list will grow over time, but for now there are two main usages:
+
+- The [`.extra()` ORM API method](https://docs.djangoproject.com/en/6.1/ref/models/querysets/#extra)
+  - The [`.extra()` ORM API method](https://docs.djangoproject.com/en/6.1/ref/models/querysets/#extra) has had a note about avoiding its usage for years. Let's determine if this is something that is central to a signficant number of Django projects.
+- The [`@cache_page` decorator](https://docs.djangoproject.com/en/6.1/topics/cache/#the-per-view-cache)
+  - The `@cache_page` decorator can easily cause problems for projects by storing and serving sensitive information such as CSRF tokens and CSP nonces. Understanding how widespread the usage is of it can help determine what further changes are needed.

django_probe-0.1.0/README.md

@@ -0,0 +1,36 @@
+# Django Probe
+
+It's hard to remove features in open-source software. [Deprecation warnings exist, but people tend to ignore them](https://sethmlarson.dev/deprecations-via-warnings-dont-work-for-python-libraries). What maintainers want to know is how many people are using a feature. That's where Django Probe comes in.
+
+Django Probe allows you to share how your project uses Django. This package counts how often specific code patterns appear in your Django project and shares the aggregated information with the community.
+
+By sharing what your project uses, you help support the Django community. This allows maintainers to know what features and APIs are actually being used, removing guess work.
+
+## Quickstart
+
+```console
+$ pip install django-probe
+$ django-probe scan .                    # inspect the payload
+$ django-probe submit .                  # send it, anonymously
+```
+
+No account is required. See [Getting started](https://docs.djangoprobe.org/getting-started/)
+for project keys, and [Privacy](https://docs.djangoprobe.org/privacy/)
+for exactly what a payload contains.
+
+### Reporting automatically
+
+You should avoid reporting this manually. The project key can be set as an environment
+variable (`DJANGO_PROBE_PROJECT_KEY`), so it drops straight into a scheduled GitHub
+Action as a repository secret. See
+[Getting started](https://docs.djangoprobe.org/getting-started/#reporting-on-a-schedule)
+for a workflow you can copy.
+
+## What we're looking to learn
+
+This list will grow over time, but for now there are two main usages:
+
+- The [`.extra()` ORM API method](https://docs.djangoproject.com/en/6.1/ref/models/querysets/#extra)
+  - The [`.extra()` ORM API method](https://docs.djangoproject.com/en/6.1/ref/models/querysets/#extra) has had a note about avoiding its usage for years. Let's determine if this is something that is central to a signficant number of Django projects.
+- The [`@cache_page` decorator](https://docs.djangoproject.com/en/6.1/topics/cache/#the-per-view-cache)
+  - The `@cache_page` decorator can easily cause problems for projects by storing and serving sensitive information such as CSRF tokens and CSP nonces. Understanding how widespread the usage is of it can help determine what further changes are needed.

django_probe-0.1.0/pyproject.toml

@@ -0,0 +1,169 @@
+[build-system]
+build-backend = "hatchling.build"
+requires = [
+  "hatchling",
+]
+
+[project]
+name = "django-probe"
+dynamic = [ "version" ]
+description = "Count Django code patterns in a project and report the counts."
+readme = "README.md"
+keywords = [
+  "AST",
+  "Django",
+  "metrics",
+]
+license = "MIT"
+authors = [
+  { name = "Django Probe contributors" },
+]
+requires-python = ">=3.11"
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: Django",
+  "Intended Audience :: Developers",
+  "Natural Language :: English",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Typing :: Typed",
+]
+dependencies = []
+scripts.django-probe = "django_probe.main:main"
+urls.Repository = "https://github.com/django-probe/django-probe"
+
+[dependency-groups]
+# Groups rather than extras: they stay out of the published wheel's metadata, so
+# installing django-probe pulls in neither Django nor pytest.
+webapp = [
+  "django>=5.0",
+  "django-allauth[socialaccount]>=65",
+  "django-ratelimit>=4.1",
+  "dj-database-url>=2.3",
+  "django-redis>=5.4",
+  "gunicorn>=23",
+  "psycopg[binary]>=3.2",
+  "whitenoise>=6.8",
+]
+test = [
+  "pytest>=8",
+  "pytest-django>=4.9",
+  "pytest-randomly",
+]
+dev = [
+  "mypy>=1.13",
+  "pre-commit>=4",
+  "ruff>=0.8",
+  { include-group = "webapp" },
+  { include-group = "test" },
+]
+docs = [ "zensical==0.0.57" ]
+# Pinned Django versions for the tox test matrix only, kept out of `dev`.
+django50 = [ "django>=5.0,<5.1" ]
+django52 = [ "django>=5.2,<6" ]
+django60 = [ "django>=6.0,<6.1; python_version>='3.12'" ]
+django61 = [ "django>=6.1,<6.2; python_version>='3.12'" ]
+djangomain = [ "django @ git+https://github.com/django/django.git@main ; python_version>='3.12'" ]
+
+[tool.uv]
+# django61/djangomain track pre-release and dev Django builds; allow uv to
+# resolve pre-releases project-wide so the lockfile's resolution mode stays
+# consistent across every tox env (a per-env override desyncs `uv sync
+# --locked` from the lockfile's recorded mode).
+prerelease = "allow"
+conflicts = [
+  [
+    { group = "django50" },
+    { group = "django52" },
+    { group = "django60" },
+    { group = "django61" },
+    { group = "djangomain" },
+  ],
+]
+
+[tool.hatch.version]
+source = "code"
+path = "src/django_probe/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = [ "src/django_probe" ]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src/django_probe",
+  "/README.md",
+]
+
+[tool.ruff]
+extend-exclude = [ "*/migrations/*" ]
+lint.select = [
+  # flake8-bugbear
+  "B",
+  # flake8-comprehensions
+  "C4",
+  # pycodestyle
+  "E",
+  # Pyflakes errors
+  "F",
+  # isort
+  "I",
+  # flake8-simplify
+  "SIM",
+  # flake8-tidy-imports
+  "TID",
+  # pyupgrade
+  "UP",
+  # Pyflakes warnings
+  "W",
+]
+lint.ignore = [
+  # flake8-bugbear opinionated rules
+  "B9",
+  # line-too-long
+  "E501",
+  # suppressible-exception
+  "SIM105",
+  # if-else-block-instead-of-if-exp
+  "SIM108",
+]
+lint.extend-safe-fixes = [
+  # non-pep585-annotation
+  "UP006",
+]
+lint.isort.known-first-party = [ "config", "django_probe", "ingest", "tests" ]
+lint.isort.required-imports = [ "from __future__ import annotations" ]
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers"
+DJANGO_SETTINGS_MODULE = "config.settings"
+pythonpath = [ ".", "src", "src/webapp" ]
+testpaths = [ "tests", "src/webapp" ]
+markers = [
+  "webapp: exercises src/webapp rather than the django_probe library",
+]
+
+[tool.mypy]
+mypy_path = "src/"
+namespace_packages = false
+warn_unreachable = true
+enable_error_code = [
+  "ignore-without-code",
+  "redundant-expr",
+  "truthy-bool",
+]
+strict = true
+overrides = [
+  { module = "tests.*", allow_untyped_defs = true },
+  # The webapp is a Django app; annotating views and models fully needs
+  # django-stubs, which is more machinery than this POC warrants.
+  { module = "config.*", ignore_errors = true },
+  { module = "ingest.*", ignore_errors = true },
+]
+
+[tool.django_probe]
+project_key = "1f3d9c62-8a41-4b7e-9d05-6c2e8f0a3b17"

django_probe-0.1.0/src/django_probe/__init__.py

@@ -0,0 +1,11 @@
+"""Django Probe. Count Django code patterns and report only the counts."""
+
+from __future__ import annotations
+
+import os
+
+__all__ = ["__version__"]
+
+# Suffixed with DJANGO_PROBE_VERSION_DEV so CI can build throwaway dev
+# distributions to test the release process. See .github/workflows/test_release.yml
+__version__ = "0.1.0" + os.environ.get("DJANGO_PROBE_VERSION_DEV", "")

django_probe-0.1.0/src/django_probe/ast_probe.py

@@ -0,0 +1,122 @@
+"""Count probe hits with a small dispatch-by-node-type AST visitor."""
+
+from __future__ import annotations
+
+import ast
+import re
+from collections import Counter, defaultdict
+from collections.abc import Callable, Iterable
+from functools import cached_property
+from typing import Any
+
+ProbeFunc = Callable[["State", Any, tuple[ast.AST, ...]], Iterable[Any]]
+
+settings_re = re.compile(r"(\b|_)settings(\b|_)")
+
+
+class State:
+    """Per-file state threaded through every probe callback."""
+
+    #: ``__weakref__`` lets probes key a ``WeakKeyDictionary`` by ``State`` (see
+    #: ``probes.orm``'s per-file ``Library`` tracking); ``__dict__`` backs
+    #: ``cached_property``.
+    __slots__ = ("filename", "from_imports", "__weakref__", "__dict__")
+
+    def __init__(self, filename: str, from_imports: defaultdict[str, set[str]]) -> None:
+        self.filename = filename
+        self.from_imports = from_imports
+
+    @cached_property
+    def looks_like_settings_file(self) -> bool:
+        return settings_re.search(self.filename) is not None
+
+
+class _Registration:
+    """One probe's AST callbacks and optional file-level gate."""
+
+    __slots__ = ("key", "condition", "ast_funcs")
+
+    def __init__(self, key: str, condition: Callable[[State], bool] | None) -> None:
+        self.key = key
+        self.condition = condition
+        self.ast_funcs: dict[type[ast.AST], list[ProbeFunc]] = defaultdict(list)
+
+
+#: Every probe registered so far, keyed by "namespace:name", populated at import time
+#: by ``probes.Probe``.
+_REGISTRY: dict[str, _Registration] = {}
+
+
+def register_probe(
+    key: str, condition: Callable[[State], bool] | None
+) -> _Registration:
+    if key in _REGISTRY:
+        raise RuntimeError(f"probe {key!r} is already registered")
+    registration = _Registration(key, condition)
+    _REGISTRY[key] = registration
+    return registration
+
+
+def probe_names() -> frozenset[str]:
+    return frozenset(_REGISTRY)
+
+
+def _probe_funcs(state: State) -> dict[type[ast.AST], list[tuple[str, ProbeFunc]]]:
+    funcs: dict[type[ast.AST], list[tuple[str, ProbeFunc]]] = defaultdict(list)
+    for registration in _REGISTRY.values():
+        if registration.condition is not None and not registration.condition(state):
+            continue
+        for type_, type_funcs in registration.ast_funcs.items():
+            funcs[type_].extend((registration.key, f) for f in type_funcs)
+    return funcs
+
+
+def _record_imports(node: ast.AST, state: State) -> None:
+    """Track imported names by module.
+
+    Every module is tracked, not just ``django.*``, since third-party probes need it;
+    and plain ``import a.b`` is recorded, which is what lets a probe match the fully
+    dotted ``@django.tasks.task`` form.
+    """
+    if isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
+        state.from_imports[node.module].update(
+            alias.name
+            for alias in node.names
+            if alias.asname is None and alias.name != "*"
+        )
+    elif isinstance(node, ast.Import):
+        for alias in node.names:
+            if alias.asname is None:
+                root = alias.name.partition(".")[0]
+                state.from_imports[root].add(root)
+
+
+def count_patterns(tree: ast.Module, filename: str) -> Counter[str]:
+    """Return ``{"namespace:probe_name": count}`` for one parsed module."""
+    state = State(filename=filename, from_imports=defaultdict(set))
+    funcs = _probe_funcs(state)
+    counts: Counter[str] = Counter()
+
+    # A stack with reversed fields gives depth-first source order. Probes rely on
+    # that, since it guarantees a module's imports are seen before the code using them.
+    nodes: list[tuple[ast.AST, tuple[ast.AST, ...]]] = [(tree, ())]
+    while nodes:
+        node, parents = nodes.pop()
+
+        for probe_name, func in funcs.get(type(node), ()):
+            for _ in func(state, node, parents):
+                counts[probe_name] += 1
+
+        _record_imports(node, state)
+
+        subparents = (*parents, node)
+        for name in reversed(node._fields):
+            value = getattr(node, name, None)
+            if isinstance(value, ast.AST):
+                nodes.append((value, subparents))
+            elif isinstance(value, list):
+                for subvalue in reversed(value):
+                    if isinstance(subvalue, ast.AST):
+                        nodes.append((subvalue, subparents))
+
+    return counts

django_probe-0.1.0/src/django_probe/collect.py

@@ -0,0 +1,53 @@
+"""Gather the non-pattern half of the payload: versions and installed dependencies."""
+
+from __future__ import annotations
+
+import platform
+import re
+from importlib import metadata
+
+_NORMALIZE_RE = re.compile(r"[-_.]+")
+
+#: Recorded in every payload so a zero count can be told apart from "nothing looked".
+PROBE_SOURCE_DISTRIBUTIONS = ("django-probe",)
+
+
+def normalize(name: str) -> str:
+    """PEP 503 name normalization."""
+    return _NORMALIZE_RE.sub("-", name).lower()
+
+
+def dependencies() -> dict[str, str]:
+    found: dict[str, str] = {}
+    for dist in metadata.distributions():
+        name = dist.metadata["Name"]
+        if name:
+            found[normalize(name)] = dist.version or ""
+    return dict(sorted(found.items()))
+
+
+def _version_of(name: str) -> str | None:
+    try:
+        return metadata.version(name)
+    except metadata.PackageNotFoundError:
+        return None
+
+
+def probe_sources() -> dict[str, str]:
+    return {
+        name: version
+        for name in PROBE_SOURCE_DISTRIBUTIONS
+        if (version := _version_of(name)) is not None
+    }
+
+
+def python_version() -> str:
+    return platform.python_version()
+
+
+def django_version() -> str:
+    return _version_of("django") or ""
+
+
+def client_version() -> str:
+    return _version_of("django-probe") or "0.0.0"

django_probe-0.1.0/src/django_probe/config.py

@@ -0,0 +1,40 @@
+"""Read the optional project key from pyproject.toml.
+
+The key is a random UUID rather than a hash of the git remote. A hashed remote would
+be zero-config, but public repositories are enumerable, so such a hash is reversible
+by dictionary attack. A UUID has no preimage.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+
+PROJECT_KEY_ENV = "DJANGO_PROBE_PROJECT_KEY"
+
+
+def pyproject_path(root: Path) -> Path:
+    return root / "pyproject.toml"
+
+
+def read_project_key(root: Path) -> str | None:
+    path = pyproject_path(root)
+    if not path.is_file():
+        return None
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError):
+        return None
+    key = data.get("tool", {}).get("django_probe", {}).get("project_key")
+    return key if isinstance(key, str) and key else None
+
+
+def resolve_project_key(root: Path) -> str | None:
+    """Resolve the project key, preferring `DJANGO_PROBE_PROJECT_KEY` over pyproject.toml.
+
+    The environment variable lets a private repository report as a stable project
+    without committing a project_key to pyproject.toml.
+    """
+    env_key = os.environ.get(PROJECT_KEY_ENV)
+    return env_key or read_project_key(root)

django_probe-0.1.0/src/django_probe/main.py

@@ -0,0 +1,87 @@
+"""django-probe command line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import uuid
+from collections.abc import Sequence
+from pathlib import Path
+
+from django_probe.payload import build_payload
+from django_probe.submit import SubmitError, submit
+
+DEFAULT_SERVER = "https://api.djangoprobe.org"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="django-probe",
+        description=(
+            "Count how often a Django project uses particular APIs. Only counts are "
+            "reported. Source code, file paths and repository names are never sent."
+        ),
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    def add_common(p: argparse.ArgumentParser) -> None:
+        p.add_argument("path", nargs="?", default=".", help="Project root to scan.")
+
+    scan = sub.add_parser(
+        "scan", help="Print the payload as JSON without sending anything."
+    )
+    add_common(scan)
+
+    send = sub.add_parser("submit", help="Scan, then send the payload to a server.")
+    add_common(send)
+    send.add_argument(
+        "--server-url", default=os.environ.get("DJANGO_PROBE_SERVER", DEFAULT_SERVER)
+    )
+    send.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print the payload instead of sending it.",
+    )
+
+    sub.add_parser("init", help="Print a random project key.")
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.command == "init":
+        print(uuid.uuid4())
+        return 0
+
+    root = Path(args.path).resolve()
+
+    if not root.is_dir():
+        print(f"not a directory: {root}", file=sys.stderr)
+        return 2
+
+    payload = build_payload(root)
+
+    if args.command == "scan" or args.dry_run:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        return 0
+
+    try:
+        response = submit(payload, args.server_url)
+    except SubmitError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    total = sum(payload["patterns"].values())
+    print(
+        f"Submitted {total} pattern occurrences across "
+        f"{payload['files_scanned']} files. ({response.get('status', 'ok')})"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

django_probe-0.1.0/src/django_probe/payload.py

@@ -0,0 +1,32 @@
+"""Assemble the submission payload.
+
+Everything the server ever receives is built here, in one function, so the privacy
+claim can be checked by reading a single file: integers, package names and version
+strings, and nothing else.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from django_probe import collect
+from django_probe.config import resolve_project_key
+from django_probe.scan import scan_path
+
+SCHEMA_VERSION = 1
+
+
+def build_payload(root: Path) -> dict[str, Any]:
+    result = scan_path(root)
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "client_version": collect.client_version(),
+        "project_key": resolve_project_key(root),
+        "python_version": collect.python_version(),
+        "django_version": collect.django_version(),
+        "files_scanned": result.files_scanned,
+        "probe_sources": collect.probe_sources(),
+        "patterns": dict(sorted(result.patterns.items())),
+        "dependencies": collect.dependencies(),
+    }

django_probe-0.1.0/src/django_probe/probes/__init__.py

@@ -0,0 +1,107 @@
+"""django-probe's probes.
+
+A probe answers "how often does this codebase do X?" for an X no tool will rewrite
+away: a probe yields once per occurrence and the visitor tallies the yields.
+
+Third-party packages will later ship probes the same way, under their own namespace::
+
+    probe = Probe("periodic_task", namespace="django-celery-beat")
+"""
+
+from __future__ import annotations
+
+import ast
+import pkgutil
+from collections.abc import Callable, Iterable
+
+from django_probe.ast_probe import ProbeFunc, State, register_probe
+
+DEFAULT_NAMESPACE = "probe"
+
+
+class Probe:
+    """A named counter over AST nodes."""
+
+    def __init__(
+        self,
+        name: str,
+        namespace: str = DEFAULT_NAMESPACE,
+        condition: Callable[[State], bool] | None = None,
+    ) -> None:
+        if any(c in name or c in namespace for c in ":."):
+            raise RuntimeError(
+                "probe names and namespaces must not contain ':' or '.': "
+                "':' separates them in the registry key"
+            )
+        self._registration = register_probe(f"{namespace}:{name}", condition)
+
+    def register(self, type_: type[ast.AST]) -> Callable[[ProbeFunc], ProbeFunc]:
+        def decorator(func: ProbeFunc) -> ProbeFunc:
+            self._registration.ast_funcs[type_].append(func)
+            return func
+
+        return decorator
+
+
+def hit(node: ast.AST) -> Iterable[None]:
+    """Yield a single countable occurrence.
+
+    ``count_patterns`` only tallies how many times a probe yields, not what it yields;
+    ``node`` documents at the call site what was hit.
+    """
+    yield None
+
+
+def dotted_name(node: ast.expr) -> str | None:
+    """Return the dotted path of a decorator or call target.
+
+    ``@task`` gives ``"task"`` and ``@django.tasks.task`` gives the full path. None if
+    any segment is not a plain name or attribute.
+    """
+    target = node.func if isinstance(node, ast.Call) else node
+    parts: list[str] = []
+    while isinstance(target, ast.Attribute):
+        parts.append(target.attr)
+        target = target.value
+    if not isinstance(target, ast.Name):
+        return None
+    parts.append(target.id)
+    return ".".join(reversed(parts))
+
+
+def resolves_to(state: State, node: ast.expr, module: str, name: str) -> bool:
+    """Whether a decorator or call target refers to ``module.name``.
+
+    Handles the three import forms reaching the same object::
+
+        from django.tasks import task      ->  @task
+        from django import tasks           ->  @tasks.task
+        import django.tasks                ->  @django.tasks.task
+
+    Aliased imports are not resolved: tracking rebindings would need real scope
+    analysis.
+    """
+    dotted = dotted_name(node)
+    if dotted is None:
+        return False
+
+    if dotted == name:
+        return name in state.from_imports[module]
+
+    parent, _, leaf = module.rpartition(".")
+    if parent and dotted == f"{leaf}.{name}":
+        return leaf in state.from_imports[parent]
+
+    if dotted == f"{module}.{name}":
+        root = module.partition(".")[0]
+        return root in state.from_imports[root]
+
+    return False
+
+
+def _import_probes() -> None:
+    for _, name, _ in pkgutil.walk_packages(__path__, f"{__name__}."):
+        __import__(name, fromlist=["_trash"])
+
+
+_import_probes()

django_probe-0.1.0/src/django_probe/probes/auth.py

@@ -0,0 +1,61 @@
+"""Detect a custom user model.
+
+Two signals, kept separate because they answer different questions: a project can set
+``AUTH_USER_MODEL`` to a third-party model without defining one itself.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Iterable
+
+from django_probe.ast_probe import State
+from django_probe.probes import Probe, hit
+
+BASES = frozenset({"AbstractUser", "AbstractBaseUser"})
+MODULE = "django.contrib.auth.models"
+BASE_MODULE = "django.contrib.auth.base_user"
+
+custom_user_model = Probe("custom_user_model")
+auth_user_model_setting = Probe(
+    "auth_user_model_setting",
+    condition=lambda state: state.looks_like_settings_file,
+)
+
+
+def _is_user_base(state: State, node: ast.expr) -> bool:
+    if isinstance(node, ast.Name):
+        name = node.id
+    elif isinstance(node, ast.Attribute):
+        name = node.attr
+    else:
+        return False
+    if name not in BASES:
+        return False
+    # AbstractUser lives in auth.models and AbstractBaseUser in auth.base_user, but
+    # both are commonly re-exported; accept either path.
+    return (
+        name in state.from_imports[MODULE]
+        or name in state.from_imports[BASE_MODULE]
+        or "models" in state.from_imports["django.contrib.auth"]
+    )
+
+
+@custom_user_model.register(ast.ClassDef)
+def visit_ClassDef(
+    state: State, node: ast.ClassDef, parents: tuple[ast.AST, ...]
+) -> Iterable[object]:
+    for base in node.bases:
+        if _is_user_base(state, base):
+            yield from hit(node)
+            return
+
+
+@auth_user_model_setting.register(ast.Assign)
+def visit_Assign(
+    state: State, node: ast.Assign, parents: tuple[ast.AST, ...]
+) -> Iterable[object]:
+    for target in node.targets:
+        if isinstance(target, ast.Name) and target.id == "AUTH_USER_MODEL":
+            yield from hit(node)
+            return

django_probe-0.1.0/src/django_probe/probes/caching.py

@@ -0,0 +1,53 @@
+"""Count @cache_page usage.
+
+Covers the direct decorator, the ``method_decorator`` wrapping used on class-based
+views, and bare calls in URLconfs.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Iterable
+
+from django_probe.ast_probe import State
+from django_probe.probes import Probe, hit, resolves_to
+
+MODULE = "django.views.decorators.cache"
+
+cache_page = Probe("cache_page")
+
+
+def _is_cache_page(state: State, node: ast.expr) -> bool:
+    return resolves_to(state, node, MODULE, "cache_page")
+
+
+def _visit_def(
+    state: State,
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+    parents: tuple[ast.AST, ...],
+) -> Iterable[object]:
+    for decorator in node.decorator_list:
+        if _is_cache_page(state, decorator):
+            yield from hit(node)
+
+
+@cache_page.register(ast.Call)
+def visit_Call(
+    state: State, node: ast.Call, parents: tuple[ast.AST, ...]
+) -> Iterable[object]:
+    """`method_decorator(cache_page(60))` and `cache_page(60)(view)`.
+
+    Only counts calls that wrap or are passed to another call. Decorators are handled
+    above and would otherwise be counted twice.
+    """
+    if isinstance(node.func, ast.Call) and _is_cache_page(state, node.func):
+        yield from hit(node)
+        return
+    for arg in node.args:
+        if isinstance(arg, ast.Call) and _is_cache_page(state, arg):
+            yield from hit(node)
+            return
+
+
+for _node_type in (ast.FunctionDef, ast.AsyncFunctionDef):
+    cache_page.register(_node_type)(_visit_def)

django_probe-0.1.0/src/django_probe/probes/orm.py

@@ -0,0 +1,91 @@
+"""Count QuerySet method usage.
+
+Matched on method name, since there are no types to consult at parse time. Measured
+against Django, Wagtail, django-oscar and djangopackages, about 98% of matches are
+genuine ORM calls. ``register.filter(...)`` was the only systematic false positive,
+which is why template ``Library`` instances are tracked below.
+
+Do not change this to require a recognisable receiver such as ``.objects``. In real
+applications up to a third of ORM calls are made on local variables and custom queryset
+methods such as ``page.get_children().filter(...)``, so precision would gain about a
+point while recall lost a third.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Callable, Iterable
+from weakref import WeakKeyDictionary
+
+from django_probe.ast_probe import State
+from django_probe.probes import Probe, dotted_name, hit
+
+METHODS = ("extra", "filter", "exclude", "alias", "annotate")
+
+LIBRARY_PATHS = frozenset({"Library", "template.Library", "django.template.Library"})
+
+#: Only `filter` collides with the template-tag API; `register.exclude` is not a thing.
+LIBRARY_METHODS = frozenset({"filter"})
+
+#: Names bound to a template Library, per file.
+_libraries: WeakKeyDictionary[State, set[str]] = WeakKeyDictionary()
+
+
+def _note_library_assignment(state: State, node: ast.Assign) -> None:
+    if not isinstance(node.value, ast.Call):
+        return
+    if dotted_name(node.value) not in LIBRARY_PATHS:
+        return
+    names = _libraries.setdefault(state, set())
+    for target in node.targets:
+        if isinstance(target, ast.Name):
+            names.add(target.id)
+        elif isinstance(target, ast.Attribute):
+            # `self.library = Library()`, then `@self.library.filter`. Recording only
+            # the trailing name is coarse, but scoped to a file that builds a Library.
+            names.add(target.attr)
+
+
+def _is_library_call(state: State, node: ast.Call, method: str) -> bool:
+    if method not in LIBRARY_METHODS:
+        return False
+    receiver = node.func.value if isinstance(node.func, ast.Attribute) else None
+    known = _libraries.get(state, set())
+    if isinstance(receiver, ast.Name):
+        return receiver.id in known
+    if isinstance(receiver, ast.Attribute):
+        return receiver.attr in known
+    return False
+
+
+def _visitor(method: str) -> Callable[..., Iterable[object]]:
+    """Build a visitor bound to one method.
+
+    A single shared visitor would credit every match to all five probes.
+    """
+
+    def visit_Call(
+        state: State, node: ast.Call, parents: tuple[ast.AST, ...]
+    ) -> Iterable[object]:
+        if not isinstance(node.func, ast.Attribute) or node.func.attr != method:
+            return
+        if _is_library_call(state, node, method):
+            return
+        yield from hit(node)
+
+    return visit_Call
+
+
+def _visit_Assign(
+    state: State, node: ast.Assign, parents: tuple[ast.AST, ...]
+) -> Iterable[object]:
+    # Registers the name and counts nothing. Assignments are visited before the code
+    # below them, so a later `register.filter` sees it.
+    _note_library_assignment(state, node)
+    return ()
+
+
+for _method in METHODS:
+    _probe = Probe(f"queryset_{_method}")
+    _probe.register(ast.Call)(_visitor(_method))
+    _probe.register(ast.Assign)(_visit_Assign)

django_probe-0.1.0/src/django_probe/probes/signals.py

@@ -0,0 +1,28 @@
+"""Count @receiver-decorated signal handlers.
+
+Signals are perennially debated and nobody has usage numbers.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Iterable
+
+from django_probe.ast_probe import State
+from django_probe.probes import Probe, hit, resolves_to
+
+signal_receiver = Probe("signal_receiver")
+
+
+def _visit(
+    state: State,
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+    parents: tuple[ast.AST, ...],
+) -> Iterable[object]:
+    for decorator in node.decorator_list:
+        if resolves_to(state, decorator, "django.dispatch", "receiver"):
+            yield from hit(node)
+
+
+for _node_type in (ast.FunctionDef, ast.AsyncFunctionDef):
+    signal_receiver.register(_node_type)(_visit)

django_probe-0.1.0/src/django_probe/probes/tasks.py

@@ -0,0 +1,34 @@
+"""Count Django Tasks framework usage.
+
+Django 6.0 shipped a built-in Tasks framework. How quickly it is adopted has no other
+source of data, and unlike a deprecation the number never goes to zero because someone
+ran a codemod.
+
+Scoped to ``django.tasks``. Celery's ``@shared_task`` is a different question.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Iterable
+
+from django_probe.ast_probe import State
+from django_probe.probes import Probe, hit, resolves_to
+
+MODULE = "django.tasks"
+
+django_task = Probe("django_task")
+
+
+def _visit(
+    state: State,
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+    parents: tuple[ast.AST, ...],
+) -> Iterable[object]:
+    for decorator in node.decorator_list:
+        if resolves_to(state, decorator, MODULE, "task"):
+            yield from hit(node)
+
+
+for _node_type in (ast.FunctionDef, ast.AsyncFunctionDef):
+    django_task.register(_node_type)(_visit)

django_probe-0.1.0/src/django_probe/probes/transactions.py

@@ -0,0 +1,40 @@
+"""Count transaction.atomic usage, as a decorator or context manager."""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Iterable
+
+from django_probe.ast_probe import State
+from django_probe.probes import Probe, hit, resolves_to
+
+transaction_atomic = Probe("transaction_atomic")
+
+
+def _is_atomic(state: State, node: ast.expr) -> bool:
+    return resolves_to(state, node, "django.db.transaction", "atomic")
+
+
+def _visit_with(
+    state: State, node: ast.With | ast.AsyncWith, parents: tuple[ast.AST, ...]
+) -> Iterable[object]:
+    for item in node.items:
+        if _is_atomic(state, item.context_expr):
+            yield from hit(node)
+
+
+def _visit_def(
+    state: State,
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+    parents: tuple[ast.AST, ...],
+) -> Iterable[object]:
+    for decorator in node.decorator_list:
+        if _is_atomic(state, decorator):
+            yield from hit(node)
+
+
+for _with_type in (ast.With, ast.AsyncWith):
+    transaction_atomic.register(_with_type)(_visit_with)
+
+for _def_type in (ast.FunctionDef, ast.AsyncFunctionDef):
+    transaction_atomic.register(_def_type)(_visit_def)

django_probe-0.1.0/src/django_probe/scan.py

@@ -0,0 +1,83 @@
+"""Walk a project directory and tally probe hits across its Python files."""
+
+from __future__ import annotations
+
+import ast
+import os
+import warnings
+from collections import Counter
+from collections.abc import Iterator
+from pathlib import Path
+
+import django_probe.probes  # noqa: F401  -- importing registers the probes
+from django_probe.ast_probe import count_patterns
+
+#: `migrations` is skipped deliberately: generated code would swamp the counts with
+#: model classes and `.filter()` calls nobody wrote by hand.
+SKIP_DIRS = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        ".tox",
+        ".nox",
+        ".venv",
+        "venv",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        "__pycache__",
+        "node_modules",
+        "site-packages",
+        "migrations",
+        "build",
+        "dist",
+    }
+)
+
+
+def ast_parse(contents_text: str) -> ast.Module:
+    # Real projects contain files with syntax warnings (e.g. invalid escape
+    # sequences); we can't do anything about them, so don't let them reach the user.
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        return ast.parse(contents_text.encode())
+
+
+class ScanResult:
+    def __init__(
+        self, patterns: Counter[str], files_scanned: int, files_skipped: int
+    ) -> None:
+        self.patterns = patterns
+        self.files_scanned = files_scanned
+        self.files_skipped = files_skipped
+
+
+def iter_python_files(root: Path) -> Iterator[Path]:
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [
+            d for d in dirnames if d not in SKIP_DIRS and not d.endswith(".egg-info")
+        ]
+        for filename in sorted(filenames):
+            if filename.endswith(".py"):
+                yield Path(dirpath) / filename
+
+
+def scan_path(root: Path) -> ScanResult:
+    patterns: Counter[str] = Counter()
+    scanned = skipped = 0
+
+    for path in iter_python_files(root):
+        try:
+            tree = ast_parse(path.read_text(encoding="utf-8"))
+        except (OSError, UnicodeDecodeError, SyntaxError, ValueError):
+            # Real projects contain templates, fixtures and Python 2 leftovers.
+            skipped += 1
+            continue
+
+        # Relative path only. Filename heuristics need it, and it never leaves here.
+        rel = str(path.relative_to(root)) if path.is_relative_to(root) else path.name
+        patterns.update(count_patterns(tree, rel))
+        scanned += 1
+
+    return ScanResult(patterns, scanned, skipped)

django_probe-0.1.0/src/django_probe/submit.py

@@ -0,0 +1,37 @@
+"""POST a payload to a Django Probe server, using only the standard library."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+ENDPOINT = "/api/submissions/"
+
+
+class SubmitError(Exception):
+    pass
+
+
+def submit(
+    payload: dict[str, Any], server_url: str, token: str | None = None
+) -> dict[str, Any]:
+    url = server_url.rstrip("/") + ENDPOINT
+    body = json.dumps(payload).encode("utf-8")
+
+    headers = {"Content-Type": "application/json"}
+    if token:
+        headers["Authorization"] = f"Token {token}"
+
+    request = urllib.request.Request(url, data=body, headers=headers, method="POST")
+
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            result: dict[str, Any] = json.loads(response.read().decode("utf-8"))
+            return result
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
+        raise SubmitError(f"server returned {exc.code}: {detail}") from exc
+    except urllib.error.URLError as exc:
+        raise SubmitError(f"could not reach {url}: {exc.reason}") from exc