code-annotations

What it is and what it does

code-annotations is a framework for finding and cataloging annotations embedded in source code. Originally built to detect personally identifiable information (PII) markers in codebases, it provides configurable parsers and report generators that can be extended for other annotation types. The package ships with Sphinx extensions for documenting annotations and includes support for multi-line comments and feature-toggle annotations.

The tool is designed for teams that need to audit code for sensitive data, compliance markers, or other inline metadata. It depends on click, pyyaml, Jinja2, stevedore, and python-slugify for configuration, templating, and plugin loading. The package is actively maintained and supports Python 3.12+, though it carries an Alpha development status.

Use it for:

• Scan a codebase for inline PII annotations and generate a compliance report.
• Build a custom annotation parser for feature-toggle markers and integrate it into your pipeline.
• Document code sections with Sphinx extensions that extract and render annotation metadata.
• Audit codebases for security-sensitive comments or deprecated API usage markers.
• Create a plugin via stevedore to detect custom annotation types in your organization's code.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Parses and summarizes code annotations (originally for PII detection) across codebases using configurable, extensible rules.

Yes, with conditions. Install if you need to parse and report on code annotations (especially PII detection) and are comfortable with Python 3.12+. The package is actively maintained, has no known vulnerabilities, and low install friction. However, its Alpha status suggests it may be best suited for teams already in the Open edX ecosystem or those willing to invest in customization via its plugin system.

Install

code-annotations on PyPI

pip install code-annotations

uv add code-annotations

poetry add code-annotations

Installing code-annotations

Before you install

Low friction install with stable maintenance. Active repository, recent release (154 days old), no known vulnerabilities. Requires Python 3.12+; five runtime dependencies are all well-established.

License in practice

Apache Software License 2.0 is permissive; you can use, modify, and distribute this package freely in most contexts, including commercial work, provided you include the license notice.

Quickstart

pip install code-annotations

from code_annotations.base import AnnotationConfig
from code_annotations.extensions import AnnotationExtension

config = AnnotationConfig()
extension = AnnotationExtension(config)

Requires Python 3.12 or later; earlier versions are not supported.

Verify before relying

• Specific annotation types supported beyond PII (fact sheet mentions generalization but does not list concrete examples).
• Performance characteristics on large codebases (number of files, lines, or time complexity).
• Integration points with CI/CD systems or IDEs beyond Sphinx documentation.
• Whether the package is actively used in production or primarily experimental (Development Status :: 3 - Alpha).
• Typical adoption and usage patterns outside the Open edX ecosystem.

Package facts

Evidence: code_annotations-3.0.0-py2.py3-none-any.whl

Keywords: edx, pii, code, annotations

Tags

More Quality Assurance packages