Python
Knossos scans Python through the same out-of-process scanner protocol as the other languages. The worker needs Python 3.11 or newer. The bundled worker uses only the standard-library ast module and starts with the isolated, bytecode-disabled flags -I -B, plus -W ignore::SyntaxWarning so that the parser's warnings about invalid escapes in your source stay off stderr. It never imports or runs your project.
What the scanner reads
pyproject.toml: the project unit and its name, PEP 621 dependencies and optional dependencies, Poetry's[tool.poetry.dependencies],dev-dependenciesandgroup.<name>.dependenciestables, and the entry points under[project.scripts]or[tool.poetry.scripts]requirements.txtandrequirements-*.txt, for projects that keep dependencies outsidepyproject.toml.pysource files and.pyistubs- packages, identified by
__init__.py - ordinary and relative imports, with their aliases. An import under
if TYPE_CHECKING:is type-only: it runs for the type checker only, so a cycle closed by nothing but such imports is not reported, unless the same module is also imported at runtime - the source roots your packages live in:
src/when it holds no__init__.py, and the directoriespyproject.tomldeclares through setuptools (packages.find.where, the""entry ofpackage-dir), Poetry (packages[].from), Hatch (wheelpackages) or PDM (build.package-dir)
A console script such as shop.cli:main maps to the exact path shop/cli.py, and a .py file listed in [tool.vulture] paths (a whitelist vulture reads as source) is an entry point too. The mapping only applies when that path produced a scanner node, so a manifest cannot invent an entry point.
Discovery skips .venv, venv, __pycache__, .tox, .mypy_cache and .pytest_cache by default, along with the other directories every language skips.
Module names
A module is named by its dotted path below the source root it sits in, and the bare project root is always the first source root. So src/shop/cart.py in a src layout is shop.cart, while app/models/user.py is app.models.user whether or not app/ holds an __init__.py: any other top-level directory is a package or a namespace package, not a source root.
An import names the module by the file it finds, so import shop.cart and import src.shop.cart both reach shop.cart. A bare import in a script, or in a module whose directory holds no __init__.py (such as a test module pytest runs), also finds the file beside it, because that directory is first on sys.path when it runs. A file that puts a directory on the path itself, with sys.path.insert(..) or sys.path.append(..) of a path built from __file__ (Path(__file__).resolve().parents[1], .parent / "lib", or os.path.dirname, abspath and join), finds a bare import in that directory too, when no source root has the module.
Two files never share a module id. When an import of a file's name finds another file (utils.py at the root and src/utils.py, or mod.py beside a mod/ package), the file the import finds keeps the name and the other one is named by its path, utils.<src/utils.py>, with a PY_MODULE_ID_COLLISION warning. A stub beside its module (mod.pyi beside mod.py) is named the same way, mod.<mod.pyi>, without a warning. A stub with no module beside it, such as the stub of an extension module, is the module an import finds, so its names resolve. Every symbol of a .pyi file is a declaration that the dead-code analysis leaves out.
What ends up in the graph
The worker emits modules, packages, classes, functions, methods, containment, imports, inheritance and the calls it can resolve statically. Async status and decorator names are kept as node attributes. A reference to a function or class that is not a call, such as one passed as an argument, becomes a references edge.
A call is attributed to a class when its receiver's class is known: a parameter or attribute annotated with the class, including Cls | None, Optional[Cls] and any of them written as a string, or a value built as Cls(), including the default in self.x = injected or Cls(). An attribute annotated in the class body (index: Cls, with or without a value, as a dataclass or a mixin declares it) types self.index in every method of that class, unless a method assigns it a different class the scan can see. A subclass inherits the annotation from its bases and mixins, in this module or another, and the nearest class that annotates the attribute decides. A base counts whether it is imported by name (class C(Base)) or named through its module (class C(models.Base) after import models or from app import models).
A call through a project class's own name, Cls.build() or models.Cls.build(), is attributed to that class's static, class or plain method. A member the class inherits is named on Cls, and the core resolves it to the base class that declares it.
A cross-file reference resolves when the declaration is in the same scan request. Anything else stays an explicit unresolved or external fact.
Some code is never called or imported by name. The scanner marks it, so it stays off the dead-code candidates list:
- A module with a shebang, or with an
if __name__ == "__main__":guard, isexecutable. So is a module that builds a served app at module level:FastAPI(),Flask(__name__), Starlette, Quart, Litestar, or Django'sget_wsgi_application()andget_asgi_application(). A server such as uvicorn loads that module by name. - A function a decorator hands to an object (
@queue.register("scan"),@bus.on) isruntime_invoked. - A module whose file name no import can spell (
029_seed.py) isruntime_invoked, together with its public top-level functions, because a loader reads it by path.
A name a package imports is an attribute of that package, so config.staging_dir() reaches the submodule that config/__init__.py re-exports it from. A class declared under if TYPE_CHECKING: is a module-level name.
Frameworks
The worker recognizes a framework from what a file imports. It reads no framework hint from the request, so recognizable code is enriched even when the dependency metadata is incomplete or absent.
| Framework | Recognized source | Graph facts |
|---|---|---|
| FastAPI | FastAPI and APIRouter objects, HTTP decorators, Depends in parameters and decorator lists, include_router, add_middleware | route nodes, routes_to, depends_on, mounts and uses_middleware edges, and the fastapi.route_handler role |
| Django | path and re_path in urlpatterns (also += and lists joined with +), include(), DRF DefaultRouter/SimpleRouter registrations, function and class-based views, models.Model bases, __call__ middleware, INSTALLED_APPS, MIDDLEWARE, ROOT_URLCONF, ASGI_APPLICATION and WSGI_APPLICATION | route and setting nodes, routes_to and configures edges, and the django.model, django.view and django.middleware roles |
| Flask | Flask and Blueprint objects, @app.route and @blueprint.route, register_blueprint, add_url_rule, MethodView subclasses | route nodes, routes_to and mounts edges, with every method of a multi-method decorator kept, and the flask.view and flask.route_handler roles |
| Celery | task and shared_task decorators; <task>.delay(...) and <task>.apply_async(...) on a project function; a signature, <task>.s(...), .si(...) or .signature(...); a task sent by name, <app>.send_task("pkg.tasks.name") or celery.signature("pkg.tasks.name") | the python.task role; a dispatches edge from the submitter to the task it queues, which flow follows. A signature's edge is probable and carries celery: signature, since it queues the task once a chain, a chord or its caller applies it. A name is read as Celery's default, module then function; a name the module does not declare, such as a custom name=, is kept only when that function exists |
Blueprint prefixes and route paths combine only when both are literals in the same file, for a decorated route and for add_url_rule alike. An APIRouter or Blueprint assigned to a name at module level is a router node, py:router:<module>.<name>, and a mounts edge from include_router or register_blueprint reaches the router node it names, in the same file or imported from another module. A router built inside a function belongs to each call of it, so it has no node, and routes declared on it read an unknown prefix, as does an add_url_rule on an object whose type the scan cannot see. A router handed in as a parameter has no node of its own either, so its mount is kept only when its target resolves. One module mounting one router twice under two prefixes keeps a mounts edge for each prefix.
HTTP clients and routes
A call to requests.get, post, put, patch, delete, head or options, to requests.request(method, url) (also with method= and url= keywords) and to the same functions of httpx becomes an endpoint node and a calls_endpoint edge from the enclosing function, when the URL is a literal or an f-string and the name resolves to the imported module. taskqueue.add(url=...) and taskqueue.Task(url=...) from google.appengine.api give an endpoint and a dispatches edge, since the request happens later. The method is POST when method= is absent, and ANY when it is not a literal, as it is for requests.request with a method read from a variable. requests.Session() and httpx.Client() receivers are not read.
To let the core join these to the routes above, a route node says which router it hangs under, a mounts edge says which router it is mounted onto, and a Django route node carries the module that holds its urlpatterns. A Django include() is a mounts edge from the including urlconf, onto itself, with the pattern's path as its prefix, to the included module (by dotted name, also in an include((module, namespace)) tuple) or to a DRF router's urls. A DRF router.register(prefix, ViewSet) gives two routes on that router, <prefix>/ and <prefix>/{pk}/, both to the viewset class; @action routes are not read. A Django route has a known prefix when its chain of includes reaches the module ROOT_URLCONF names. From request to handler describes the join.
Limits
- Dynamic imports, monkey-patching, runtime decorator effects, metaclass behavior and dynamically selected call targets are not executed or inferred. A decorator name is structural evidence, not a claim about what it does at runtime.
- A route path that is not a string literal is skipped with
PY_DYNAMIC_ROUTE_PATH. A Flask converter path such as/users/<int:user_id>is a template and kept as written. - Django settings are limited to the five names above with statically literal values, and a settings module is never imported. FastAPI dependency callables are never invoked.
- A syntax error produces
PY_SYNTAX_ERRORfor that file, a file the worker cannot read or that is oversized producesPY_UNSCANNABLE_FILE, and neither stops the other files from contributing. - A relative import that climbs above the project root emits no edge and reports
PY_UNRESOLVED_RELATIVE_IMPORT. A module file and a package that share one module id both reportPY_MODULE_ID_COLLISION; the package keeps the id.
Processes it starts
A list or tuple that reads as the argv of a process links the code that builds it to the file the process runs, with a probable launches edge to that file's module: [sys.executable, ..., str(ROOT / "worker.py")], ["node", "js/worker.js"], or a program path joined to a root in first place ([str(ROOT) + "/bin/tool"]). A path is a string literal or the literal parts it is joined from (/, +, an f-string, os.path.join); a name with no directory counts only with a script's extension. The core resolves the path to the module of the project file at that path, or of the one file whose path ends with it, and drops the edge when there is none.