Introducing metacode: machine-readable instructions in comments.

Developers often need to place a small instruction beside one line of code: ignore this warning, stop formatting here, or exclude this line from coverage. Python tools express these instructions through comments such as noqa, type: ignore, and fmt: off. Each tool has its own syntax and parser, so new analyzers repeat the same work and can misread comments intended for another tool.

Decorators, typing.Annotated, and project configuration work at other scopes. Inline instructions need a shared syntax that leaves their meaning to each tool.

metacode is a Python library for reading specially formatted instructions from comments. It defines one compact key: command[arguments] shape that different source-code tools can share while giving each tool its own key and commands. The release is available on GitHub.

Syntax and responsibilities🔗

A metacode directive has a key, a command, and optional arguments:

# mutating: ignore[comparison]
# fmt: off
# type: ignore[attr-defined]

metacode parses key: command[arguments] into ParsedComment records. Arguments may contain common Python literals and names, or—when enabled—inert AST nodes that metacode never executes.

The caller supplies its own key, so unrelated directives on the same line are ignored:

from metacode import parse

comment = "mutating: ignore[comparison] # fmt: off"

print(parse(comment, "mutating"))
#> [ParsedComment(key='mutating', command='ignore', arguments=['comparison'])]

Several hash-separated directives can share a line. Each tool requests its own key and decides what the parsed command means.

metacode parses comment text only. It does not read files, attach coordinates or syntax nodes, or decide the scope of a command.

Why another convention?🔗

metacode does not replace every pragma. # type: ignore[code], # fmt: off, and # isort: skip fit its grammar; # noqa, # nosec, # pragma: no cover, and Pylint’s syntax require adapters or native support.

Python’s doctest directives define a comment language for one domain; Go tool directives share a namespaced syntax across tools.

Comments place a local instruction beside the relevant code, have no runtime effect, and require no imports. Project configuration is better for broad policy; an inline directive can describe an exception that applies to one expression.

Use in source-processing tools🔗

Other source-code libraries locate comments; metacode reads their contents. A tool can therefore keep finding comments, understanding instructions, and applying its own rules as separate steps.

Until independent tools adopt the grammar, metacode is a reusable convention and parser rather than an ecosystem standard.

What comes next🔗

The project will add reliable ways to both read and write these instructions without damaging ordinary comments.