---
id: code-annotations
version: "3.0.0"
license: Apache Software License 2.0
license_treatment: permissive
maintenance: active
---

# code-annotations — Extensible tools for parsing annotations in codebases

License: permissive · Maintenance: active · Downloads: 105.2K/mo

## 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 above — 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

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

- License: Apache Software License 2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 105.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

code annotation parsing, pii detection in code, codebase annotation tools, code scanning and tagging, annotation extraction framework, configurable code linting, annotation reporting, code-scanning, pii-detection, extensible-framework

[View on SkillFed](https://skillfed.io/packages/code-annotations) · [View on PyPI](https://pypi.org/project/code-annotations/)