{"id":9596,"library":"code-annotations","title":"Extensible Code Annotation Parser","description":"code-annotations provides extensible tools for parsing annotations within codebases. It allows users to define custom annotation contexts and search for specific patterns across various file types. The library is currently at version 3.0.0, with frequent dependency updates and regular minor/major releases.","status":"active","version":"3.0.0","language":"en","source_language":"en","source_url":"https://github.com/openedx/code-annotations","tags":["code analysis","annotations","static analysis","developer tools"],"install":[{"cmd":"pip install code-annotations","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for caching mechanisms within the annotation processing.","package":"django-cache-annotation"}],"imports":[{"symbol":"find_annotations","correct":"from code_annotations.find_annotations import find_annotations"},{"symbol":"AnnotationContext","correct":"from code_annotations.annotation_contexts import AnnotationContext"}],"quickstart":{"code":"import tempfile\nimport os\nimport shutil\nfrom pathlib import Path\nfrom code_annotations.find_annotations import find_annotations\nfrom code_annotations.annotation_contexts import AnnotationContext\n\n# 1. Define a custom AnnotationContext\nclass MyCustomAnnotationContext(AnnotationContext):\n    \"\"\"\n    A simple context to find annotations like:\n    # TODO: Finish this feature\n    # REVIEW: Check performance\n    \"\"\"\n    context_name = \"MY_CUSTOM\"\n\n    @staticmethod\n    def is_inline_annotation_context(line):\n        return \"# TODO:\" in line or \"# REVIEW:\" in line\n\n    @staticmethod\n    def get_inline_annotation_key(line):\n        if \"# TODO:\" in line:\n            return \"TODO\"\n        elif \"# REVIEW:\" in line:\n            return \"REVIEW\"\n        return None\n\n    @staticmethod\n    def get_inline_annotation_value(line):\n        if \"# TODO:\" in line:\n            return line.split(\"# TODO:\", 1)[1].strip()\n        elif \"# REVIEW:\" in line:\n            return line.split(\"# REVIEW:\", 1)[1].strip()\n        return None\n\n# 2. Create a dummy file in a temporary directory\ntemp_dir = Path(tempfile.mkdtemp())\ndummy_file = temp_dir / \"example_code.py\"\ndummy_file.write_text(\"\"\"\ndef my_function():\n    # TODO: Implement actual logic\n    print(\"Hello, World!\")\n    # REVIEW: This might be slow for large inputs\n    pass\n\nclass MyClass:\n    # TODO: Add docstrings\n    def __init__(self):\n        pass\n\"\"\")\n\ntry:\n    # 3. Find annotations\n    results = find_annotations(\n        src_dir=str(temp_dir),\n        annotation_contexts=[MyCustomAnnotationContext],\n        file_extensions=['.py'],\n        root_dir_to_scan=str(temp_dir),\n    )\n\n    # 4. Print results\n    print(f\"Found annotations in: {temp_dir}\")\n    for file_path, annotations in results.items():\n        print(f\"  File: {file_path}\")\n        for annotation in annotations:\n            print(f\"    [{annotation.context_name}] {annotation.key}: {annotation.value} at line {annotation.line}\")\n\nfinally:\n    # Clean up the temporary directory\n    shutil.rmtree(temp_dir)\n","lang":"python","description":"This quickstart demonstrates how to define a custom AnnotationContext to identify specific comment-based annotations (like TODOs and REVIEWs) and then use `find_annotations` to scan a temporary Python file for these annotations."},"warnings":[{"fix":"Ensure your project uses Python 3.12 or newer, or pin `code-annotations` to a version prior to 3.0.0 if Python 3.11 support is required (e.g., `code-annotations<3.0.0`).","message":"Version 3.0.0 of `code-annotations` dropped support for Python 3.11. It now requires Python >=3.12.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade your Python environment to 3.11+ or pin `code-annotations` to a version prior to 2.0.0 (e.g., `code-annotations<2.0.0`).","message":"Version 2.0.0 of `code-annotations` dropped support for Python 3.8. It moved to supporting Python 3.11 and 3.12 at that time.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Thoroughly test your custom `AnnotationContext` classes with diverse code examples. Refer to the official documentation and examples for best practices on context definition.","message":"The core functionality relies on custom `AnnotationContext` implementations. Incorrectly defining `is_inline_annotation_context`, `get_inline_annotation_key`, or `get_inline_annotation_value` can lead to missed annotations or parsing errors.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install code-annotations` to install the library.","cause":"The `code-annotations` library is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'code_annotations'"},{"fix":"Upgrade your Python environment to 3.12 or newer, or install a compatible older version of `code-annotations` (e.g., `pip install 'code-annotations<3.0.0'`).","cause":"Attempting to install version 3.0.0 or later of `code-annotations` on an unsupported Python version.","error":"ERROR: Package 'code-annotations' requires Python '>=3.12', but you have Python 3.11.0."}]}