code-annotations 2.1.0__tar.gz → 2.3.0__tar.gz

{code_annotations-2.1.0 → code_annotations-2.3.0}/CHANGELOG.rst

@@ -14,10 +14,15 @@ Change Log
 Unreleased
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+[2.2.0] - 2025-01-15
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Add support for optional Open edX Event trigger in-line annotation.
+
 [2.1.0] - 2024-12-12
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* Add support for optional event warning for in-line annotation.
+* Add support for optional Open edX Event warning for in-line annotation.
 
 [2.0.0] - 2024-10-18
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

{code_annotations-2.1.0 → code_annotations-2.3.0}/MANIFEST.in

@@ -4,4 +4,4 @@ include CONTRIBUTING.rst
 include LICENSE.txt
 include README.rst
 include requirements/base.in
-recursive-include code_annotations *.html *.png *.gif *js *.css *jpg *jpeg *svg *py *.yaml *.yml
+recursive-include code_annotations *.tpl *.html *.png *.gif *js *.css *jpg *jpeg *svg *py *.yaml *.yml

{code_annotations-2.1.0 → code_annotations-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: code-annotations
-Version: 2.1.0
+Version: 2.3.0
 Summary: Extensible tools for parsing annotations in codebases
 Home-page: https://github.com/openedx/code-annotations
 Author: edX
@@ -10,6 +10,7 @@ Keywords: edx pii code annotations
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: Django
 Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.2
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Natural Language :: English
@@ -23,18 +24,28 @@ License-File: LICENSE.txt
 License-File: NOTICE.txt
 Requires-Dist: python-slugify
 Requires-Dist: stevedore
-Requires-Dist: pyyaml
 Requires-Dist: click
+Requires-Dist: pyyaml
 Requires-Dist: Jinja2
 Provides-Extra: django
 Requires-Dist: Django>=4.2; extra == "django"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 code-annotations
 =============================
 
-|pypi-badge| |CI| |codecov-badge| |doc-badge| |pyversions-badge|
-|license-badge|
-
 Extensible tools for parsing annotations in codebases
 
 Overview
@@ -88,31 +99,6 @@ refer to this `list of resources`_ if you need any assistance.
 .. _list of resources: https://open.edx.org/getting-help
 
 
-.. |pypi-badge| image:: https://img.shields.io/pypi/v/code-annotations.svg
-    :target: https://pypi.python.org/pypi/code-annotations/
-    :alt: PyPI
-
-.. |CI| image:: https://github.com/openedx/code-annotations/workflows/Python%20CI/badge.svg?branch=master
-    :target: https://github.com/openedx/code-annotations/actions?query=workflow%3A%22Python+CI%22
-    :alt: CI
-
-.. |codecov-badge| image:: http://codecov.io/github/edx/code-annotations/coverage.svg?branch=master
-    :target: http://codecov.io/github/edx/code-annotations?branch=master
-    :alt: Codecov
-
-.. |doc-badge| image:: https://readthedocs.org/projects/code-annotations/badge/?version=latest
-    :target: http://code-annotations.readthedocs.io/en/latest/
-    :alt: Documentation
-
-.. |pyversions-badge| image:: https://img.shields.io/pypi/pyversions/code-annotations.svg
-    :target: https://pypi.python.org/pypi/code-annotations/
-    :alt: Supported Python versions
-
-.. |license-badge| image:: https://img.shields.io/github/license/edx/code-annotations.svg
-    :target: https://github.com/openedx/code-annotations/blob/master/LICENSE.txt
-    :alt: License
-
-
 Change Log
 ----------
 
@@ -129,10 +115,15 @@ Change Log
 Unreleased
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+[2.2.0] - 2025-01-15
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Add support for optional Open edX Event trigger in-line annotation.
+
 [2.1.0] - 2024-12-12
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* Add support for optional event warning for in-line annotation.
+* Add support for optional Open edX Event warning for in-line annotation.
 
 [2.0.0] - 2024-10-18
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

{code_annotations-2.1.0 → code_annotations-2.3.0}/README.rst

@@ -1,9 +1,6 @@
 code-annotations
 =============================
 
-|pypi-badge| |CI| |codecov-badge| |doc-badge| |pyversions-badge|
-|license-badge|
-
 Extensible tools for parsing annotations in codebases
 
 Overview
@@ -55,28 +52,3 @@ Have a question about this repository, or about Open edX in general?  Please
 refer to this `list of resources`_ if you need any assistance.
 
 .. _list of resources: https://open.edx.org/getting-help
-
-
-.. |pypi-badge| image:: https://img.shields.io/pypi/v/code-annotations.svg
-    :target: https://pypi.python.org/pypi/code-annotations/
-    :alt: PyPI
-
-.. |CI| image:: https://github.com/openedx/code-annotations/workflows/Python%20CI/badge.svg?branch=master
-    :target: https://github.com/openedx/code-annotations/actions?query=workflow%3A%22Python+CI%22
-    :alt: CI
-
-.. |codecov-badge| image:: http://codecov.io/github/edx/code-annotations/coverage.svg?branch=master
-    :target: http://codecov.io/github/edx/code-annotations?branch=master
-    :alt: Codecov
-
-.. |doc-badge| image:: https://readthedocs.org/projects/code-annotations/badge/?version=latest
-    :target: http://code-annotations.readthedocs.io/en/latest/
-    :alt: Documentation
-
-.. |pyversions-badge| image:: https://img.shields.io/pypi/pyversions/code-annotations.svg
-    :target: https://pypi.python.org/pypi/code-annotations/
-    :alt: Supported Python versions
-
-.. |license-badge| image:: https://img.shields.io/github/license/edx/code-annotations.svg
-    :target: https://github.com/openedx/code-annotations/blob/master/LICENSE.txt
-    :alt: License

{code_annotations-2.1.0 → code_annotations-2.3.0}/code_annotations/__init__.py

@@ -2,4 +2,4 @@
 Extensible tools for parsing annotations in codebases.
 """
 
-__version__ = '2.1.0'
+__version__ = "2.3.0"

{code_annotations-2.1.0 → code_annotations-2.3.0}/code_annotations/base.py

@@ -14,6 +14,9 @@ from code_annotations import annotation_errors
 from code_annotations.exceptions import ConfigurationException
 from code_annotations.helpers import VerboseEcho
 
+PACKAGE_DIR = os.path.dirname(os.path.realpath(__file__))
+DEFAULT_TEMPLATE_DIR = os.path.join(PACKAGE_DIR, "report_templates")
+
 
 class AnnotationConfig:
     """
@@ -58,10 +61,17 @@ class AnnotationConfig:
         self.echo(f"Configured for source path: {self.source_path}")
 
         self._configure_coverage(raw_config.get('coverage_target', None))
-        self.report_template_dir = raw_config.get('report_template_dir')
-        self.rendered_report_dir = raw_config.get('rendered_report_dir')
-        self.rendered_report_file_extension = raw_config.get('rendered_report_file_extension')
-        self.rendered_report_source_link_prefix = raw_config.get('rendered_report_source_link_prefix')
+
+        self.rendered_report_format = raw_config.get('rendered_report_format', 'rst')
+        self.report_template_dir = raw_config.get(
+            'report_template_dir',
+            os.path.join(DEFAULT_TEMPLATE_DIR, self.rendered_report_format)
+        )
+        self.rendered_report_dir = raw_config.get('rendered_report_dir', 'annotation_reports')
+        self.rendered_report_source_link_prefix = raw_config.get('rendered_report_source_link_prefix', None)
+        self.trim_filename_prefixes = raw_config.get('trim_filename_prefixes', [])
+        self.third_party_package_location = raw_config.get('third_party_package_location', "site-packages")
+        self.rendered_report_file_extension = f".{self.rendered_report_format}"
 
         self._configure_annotations(raw_config)
         self._configure_extensions()

{code_annotations-2.1.0 → code_annotations-2.3.0}/code_annotations/cli.py

@@ -241,10 +241,15 @@ def generate_docs(config_file, verbosity, report_files):
     try:
         config = AnnotationConfig(config_file, verbosity)
 
+        if not report_files:
+            raise ConfigurationException(
+                "No report files provided. Please provide one or more report files to generate docs from."
+            )
+
         for key in (
             "report_template_dir",
             "rendered_report_dir",
-            "rendered_report_file_extension",
+            "rendered_report_format",
             "rendered_report_source_link_prefix",
         ):
             if not getattr(config, key):

code_annotations-2.3.0/code_annotations/contrib/config/__init__.py

@@ -0,0 +1,14 @@
+"""
+Expose contrib configuration file paths as Python variables, for use in 3rd-party utilities.
+"""
+import importlib.resources
+import os
+
+FEATURE_TOGGLE_ANNOTATIONS_CONFIG_PATH = importlib.resources.files(
+    "code_annotations") / os.path.join("contrib", "config", "feature_toggle_annotations.yaml")
+
+SETTING_ANNOTATIONS_CONFIG_PATH = importlib.resources.files(
+    "code_annotations") / os.path.join("contrib", "config", "setting_annotations.yaml")
+
+OPENEDX_EVENTS_ANNOTATIONS_CONFIG_PATH = importlib.resources.files(
+    "code_annotations") / os.path.join("contrib", "config", "openedx_events_annotations.yaml")

{code_annotations-2.1.0 → code_annotations-2.3.0}/code_annotations/contrib/config/openedx_events_annotations.yaml

@@ -12,6 +12,7 @@ annotations:
     - ".. event_description:":
     - ".. event_data:":
     - ".. event_key_field:":
+    - ".. event_trigger_repository:":
     - ".. event_warning:":
 extensions:
     python:

{code_annotations-2.1.0 → code_annotations-2.3.0}/code_annotations/contrib/sphinx/extensions/openedx_events.py

@@ -100,6 +100,7 @@ class OpenedxEvents(SphinxDirective):
             event_key_field = event.get(".. event_key_field:", "")
             event_key_literal = nodes.literal(text=event_key_field)
             event_description = event[".. event_description:"]
+            event_trigger_repository = event.get(".. event_trigger_repository:")
 
             event_section = nodes.section("", ids=[f"openedxevent-{event_type}"])
             event_section += nodes.title(text=event_type, ids=[f"title-{event_type}"])
@@ -114,10 +115,42 @@ class OpenedxEvents(SphinxDirective):
                 )
             event_section += nodes.paragraph("", "Event data: ", event_data_literal)
             event_section += nodes.paragraph(
-                text=f"Defined at: {event['filename']} (line"
-                     f" {event['line_number']})"
+                "",
+                "Defined at: ",
+                nodes.reference(
+                    text="{} (line {})".format(
+                        event["filename"], event["line_number"]
+                    ),
+                    refuri="{}/blob/{}/{}#L{}".format(
+                        self.env.config.openedxevents_repo_url,
+                        self.env.config.openedxevents_repo_version,
+                        event["filename"],
+                        event["line_number"],
+                    ),
+                ),
+                ids=[f"definition-{event_name}"],
             )
 
+            if event_trigger_repository:
+                event_trigger_repository = event_trigger_repository.split(" ")
+                event_section += nodes.paragraph(text="Triggered by:", ids=[f"triggers-{event_name}"])
+                triggers_bullet_list = nodes.bullet_list()
+                for repository in event_trigger_repository:
+                    search_url = f"https://github.com/search?q=repo:{repository}+{event_name}.send_event&type=code"
+                    triggers_bullet_list += nodes.list_item(
+                        "",
+                        nodes.paragraph(
+                            "",
+                            "",
+                            nodes.reference(
+                                text=repository,
+                                refuri=search_url,
+                            ),
+                        ),
+                    )
+
+                event_section += triggers_bullet_list
+
             if event.get(".. event_warning:") not in (None, "None", "n/a", "N/A"):
                 event_section += nodes.warning(
                     "", nodes.paragraph("", event[".. event_warning:"]), ids=[f"warning-{event_name}"]

{code_annotations-2.1.0 → code_annotations-2.3.0}/code_annotations/generate_docs.py

@@ -27,8 +27,7 @@ class ReportRenderer:
         self.config = config
         self.echo = self.config.echo
         self.report_files = report_files
-        self.create_time = datetime.datetime.utcnow().isoformat()
-
+        self.create_time = datetime.datetime.now(tz=datetime.timezone.utc)
         self.full_report = self._aggregate_reports()
 
         self.jinja_environment = jinja2.Environment(
@@ -62,6 +61,12 @@ class ReportRenderer:
         loaded_report = yaml.safe_load(report_file)
 
         for filename in loaded_report:
+            trimmed_filename = filename
+            for prefix in self.config.trim_filename_prefixes:
+                if filename.startswith(prefix):
+                    trimmed_filename = filename[len(prefix):]
+                    break
+
             if filename in report:
                 for loaded_annotation in loaded_report[filename]:
                     found = False
@@ -74,9 +79,9 @@ class ReportRenderer:
                             break
 
                     if not found:
-                        report[filename].append(loaded_annotation)
+                        report[trimmed_filename].append(loaded_annotation)
             else:
-                report[filename] = loaded_report[filename]
+                report[trimmed_filename] = loaded_report[filename]
 
     def _aggregate_reports(self):
         """
@@ -91,11 +96,12 @@ class ReportRenderer:
 
         return report
 
-    def _write_doc_file(self, doc_filename, doc_data):
+    def _write_doc_file(self, doc_title, doc_filename, doc_data):
         """
         Write out a single report file with the given data. This is rendered using the configured top level template.
 
         Args:
+            doc_title: Title to use for the document.
             doc_filename: Filename to write to.
             doc_data: Dict of reporting data to use, in the {'file name': [list, of, annotations,]} style.
         """
@@ -110,14 +116,16 @@ class ReportRenderer:
 
         with open(full_doc_filename, 'w') as output:
             output.write(self.top_level_template.render(
+                doc_title=doc_title,
                 create_time=self.create_time,
                 report=doc_data,
                 all_choices=self.all_choices,
                 all_annotations=self.config.annotation_tokens,
                 group_mapping=self.group_mapping,
                 slugify=slugify,
-                source_link_prefix=self.config.rendered_report_source_link_prefix)
-            )
+                source_link_prefix=self.config.rendered_report_source_link_prefix,
+                third_party_package_location=self.config.third_party_package_location,
+            ))
 
     def _generate_per_choice_docs(self):
         """
@@ -130,7 +138,7 @@ class ReportRenderer:
                     if isinstance(annotation['annotation_data'], list) and choice in annotation['annotation_data']:
                         choice_report[filename].append(annotation)
 
-            self._write_doc_file(f'choice_{choice}', choice_report)
+            self._write_doc_file(f"All References to Choice '{choice}'", f'choice_{choice}', choice_report)
 
     def _generate_per_annotation_docs(self):
         """
@@ -143,13 +151,15 @@ class ReportRenderer:
                     if report_annotation['annotation_token'] == annotation:
                         annotation_report[filename].append(report_annotation)
 
-            self._write_doc_file(f'annotation_{annotation}', annotation_report)
+            self._write_doc_file(
+                f"All References to Annotation '{annotation}'", f'annotation_{annotation}', annotation_report
+            )
 
     def render(self):
         """
         Perform the rendering of all documentation using the configured Jinja2 templates.
         """
         # Generate the top level list of all annotations
-        self._write_doc_file('index', self.full_report)
+        self._write_doc_file("Complete Annotation List", 'index', self.full_report)
         self._generate_per_choice_docs()
         self._generate_per_annotation_docs()

code_annotations-2.3.0/code_annotations/report_templates/html/annotation.tpl

@@ -0,0 +1,14 @@
+{% if is_third_party %}
+{# no links for third party code since we don't know where to link to #}
+{% if annotation.extra and annotation.extra.object_id %}
+{{ annotation.extra.object_id }} {% if annotation.line_number > 0 %}line {{ annotation.line_number }}{% endif %}: {{ annotation.annotation_token }} {% include "annotation_data.tpl" %}
+{% else %}
+    {% if loop.changed(annotation.line_number)%}{{ filename }}:{{ annotation.line_number }}<br />{% endif %}:
+    {{ annotation.annotation_token }} {% include "annotation_data.tpl" %}
+{% endif %}
+
+{% elif annotation.extra and annotation.extra.object_id %}
+<a href="{{ source_link_prefix }}{{ filename }}#L{{ annotation.line_number }}" target="_blank">{{ annotation.extra.object_id }} {% if annotation.line_number > 0 %}line {{ annotation.line_number }}{% endif %}</a>: {{ annotation.annotation_token }} {% include "annotation_data.tpl" %}
+{% else %}
+<a href="{{ source_link_prefix }}{{ filename }}#L{{ annotation.line_number }}" target="_blank">`{{ filename }}:{{ annotation.line_number }}: {{ annotation.annotation_token }} {% include "annotation_data.tpl" %}
+{% endif %}

code_annotations-2.3.0/code_annotations/report_templates/html/annotation_data.tpl

@@ -0,0 +1,8 @@
+{% if annotation.annotation_data is sequence and annotation.annotation_data is not string %}
+{% for a in annotation.annotation_data %}
+<a href="choice-{{ slugify(a) }}.html">{{ a }}</a>{% if not loop.last %}, {% endif %}
+{% endfor %}
+
+{% else %}
+{{ annotation.annotation_data }}
+{% endif %}

code_annotations-2.3.0/code_annotations/report_templates/html/annotation_list.tpl

@@ -0,0 +1,27 @@
+{% extends "base.tpl" %}
+{% block content %}
+Annotations found in {{ report|length }} files.
+
+{% for filename in report %}
+{% set is_third_party = third_party_package_location in filename %}
+
+<h2 id="file-{{ slugify(filename) }}">{{ filename }}</h2>
+    <div class="file-annotations">
+    {{ report[filename]|length }} annotations {% if is_third_party %}(installed package){% endif %}<br />
+    </div>
+
+    {% for annotation in report[filename] %}
+        {% if loop.changed(annotation.report_group_id) %}
+            {% if not loop.first %}</ul></div>{% endif %}
+            <div class="group-annotations"><ul>
+        {% endif %}
+                <li>{% include 'annotation.tpl' %}</li>
+        {% if loop.last %}
+            </ul></div>
+        {% endif %}
+    {% endfor %}
+
+
+{% endfor %}
+
+{% endblock %}

code_annotations-2.3.0/code_annotations/report_templates/html/base.tpl

@@ -0,0 +1,92 @@
+<html>
+<head>
+    <title>{{ doc_title }}</title>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+    <style>
+    body {
+        font-family: 'Trebuchet MS', sans-serif;
+    }
+
+    .title {
+        text-align: center;
+    }
+
+    .table {
+        display: table;
+        border-spacing: 12px;
+    }
+
+    .row {
+        display: table-row;
+        margin-bottom: 0;
+        margin-top: 0;
+        width: 100%;
+    }
+
+    .cell1 {
+        display: table-cell;
+        width: 20%;
+        margin-right: 1%;
+        border: 1px solid #ccc;
+        margin 12px;
+        background-color: #ffffee;
+    }
+
+    .cell2 {
+        display: table-cell;
+        width: 79%;
+        margin-right: 1%;
+        margin 12px;
+    }
+
+    .group-annotations {
+        border: 1px solid #ccc;
+        margin: 10px;
+    }
+    </style>
+</head>
+<body>
+<h1 class="title">{{ doc_title }}</h1>
+
+<div class="table">
+    <div class="row">
+        <div class="cell1">
+            <h3><a href="index.html">Home</a></h3>
+
+            <h3>Annotations</h3>
+
+            <ul>
+            {% for a in all_annotations %}
+                <li><a href="annotation-{{ slugify(a) }}.html">annotation_{{ slugify(a) }}</a></li>
+            {% endfor %}
+            </ul>
+
+            <h3>Choices</h3>
+
+            <ul>
+            {% for choice in all_choices %}
+                <li><a href="choice-{{ slugify(choice) }}.html">choice_{{ slugify(choice) }}</a></li>
+            {% endfor %}
+            </ul>
+        </div>
+        <div class="cell2">
+            <h2>Files in this page</h2>
+            <ul>
+            {% for filename in report %}
+                <li><a href="#file-{{ slugify(filename) }}">{{ filename }}</a></li>
+            {% endfor %}
+            </ul>
+
+            {% block content %}{% endblock %}
+        </div>
+    </div>
+</div>
+{% block footer %}
+<div class="footer">
+<br /><br />
+<hr />
+Built at {{ create_time.strftime('%Y-%m-%d %H:%M:%S %Z') }}
+</div>
+{% endblock %}
+</body>
+</html>

code_annotations-2.3.0/code_annotations/report_templates/rst/annotation.tpl

@@ -0,0 +1,13 @@
+{% if is_third_party %}
+{# no links for third party code since we don't know where to link to #}
+{% if annotation.extra and annotation.extra.object_id %}
+{{ annotation.extra.object_id }} {% if annotation.line_number > 0 %}line {{ annotation.line_number }}{% endif %}: {{ annotation.annotation_token }} {% include "annotation_data.tpl" %}
+{% else %}
+{{ filename }}:{{ annotation.line_number }}: {{ annotation.annotation_token }} {% include "annotation_data.tpl" %}
+{% endif %}
+
+{% elif annotation.extra and annotation.extra.object_id %}
+`{{ annotation.extra.object_id }} {% if annotation.line_number > 0 %}line {{ annotation.line_number }}{% endif %} <{{ source_link_prefix }}{{ filename }}#L{{ annotation.line_number }}>`_: {{ annotation.annotation_token }} {% include "annotation_data.tpl" %}
+{% else %}
+`{{ filename }}:{{ annotation.line_number }} <{{ source_link_prefix }}{{ filename }}#L{{ annotation.line_number }}>`_: {{ annotation.annotation_token }} {% include "annotation_data.tpl" %}
+{% endif %}

code_annotations-2.3.0/code_annotations/report_templates/rst/annotation_data.tpl

@@ -0,0 +1,8 @@
+{% if annotation.annotation_data is sequence and annotation.annotation_data is not string %}
+{% for a in annotation.annotation_data %}
+choice_{{ slugify(a) }}_{% if not loop.last %}, {% endif %}
+{% endfor %}
+
+{% else %}
+{{ annotation.annotation_data }}
+{% endif %}

code_annotations-2.3.0/code_annotations/report_templates/rst/annotation_group.tpl

@@ -0,0 +1,2 @@
+.. _index.rst#{{ slugify(filename + '-' + annotation.report_group_id |string) }}:
+.. admonition:: {{ group_mapping[annotation.annotation_token] or annotation.annotation_token }}

code_annotations-2.3.0/code_annotations/report_templates/rst/annotation_list.tpl

@@ -0,0 +1,34 @@
+{% extends "base.tpl" %}
+{% block content %}
+Annotations found in {{ report|length }} files.
+
+{% for filename in report %}
+{% set is_third_party = third_party_package_location in filename %}
+
+{{ filename }}
+{{ "-" * filename|length }}
+
+    .. note:: {{ report[filename]|length }} annotations {% if is_third_party %}(installed package){% endif %}
+
+
+    {% for annotation in report[filename] %}
+        {% if annotation.report_group_id %}
+            {% if loop.changed(annotation.report_group_id) %}
+                {% include 'annotation_group.tpl' %}
+
+
+            {% endif %}
+    * {% include 'annotation.tpl' %}
+
+        {% else %}
+            {% if loop.changed(annotation.report_group_id) %}
+
+            {% endif %}
+* {% include 'annotation.tpl' %}
+
+        {% endif %}
+    {% endfor %}
+
+{% endfor %}
+
+{% endblock %}

code_annotations-2.3.0/code_annotations/report_templates/rst/base.tpl

@@ -0,0 +1,41 @@
+{{ "#" * doc_title|length }}
+{{ doc_title }}
+{{ "#" * doc_title|length }}
+
+.. sidebar:: Table of Contents
+
+    `Home <index.rst>`_
+
+    Annotations
+
+    {% for a in all_annotations %}
+        * annotation_{{ slugify(a) }}_
+    {% endfor %}
+
+    Choices
+
+    {% for choice in all_choices %}
+        * choice_{{ slugify(choice) }}_
+    {% endfor %}
+
+
+.. contents::
+
+{% block content %}{% endblock %}
+
+
+{# backlinks for all choices #}
+{% for choice in all_choices %}
+.. _choice_{{ slugify(choice) }}: {{ slugify('choice_' + choice) + '.rst' }}
+{% endfor %}
+
+
+{# backlinks for all annotations #}
+{% for annotation in all_annotations %}
+.. _annotation_{{ slugify(annotation) }}: {{ slugify('annotation_' + annotation) + '.rst' }}
+{% endfor %}
+
+
+{% block footer %}
+Built at {{ create_time.strftime('%Y-%m-%d %H:%M:%S %Z') }}
+{% endblock %}

{code_annotations-2.1.0 → code_annotations-2.3.0}/code_annotations.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: code-annotations
-Version: 2.1.0
+Version: 2.3.0
 Summary: Extensible tools for parsing annotations in codebases
 Home-page: https://github.com/openedx/code-annotations
 Author: edX
@@ -10,6 +10,7 @@ Keywords: edx pii code annotations
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: Django
 Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.2
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Natural Language :: English
@@ -23,18 +24,28 @@ License-File: LICENSE.txt
 License-File: NOTICE.txt
 Requires-Dist: python-slugify
 Requires-Dist: stevedore
-Requires-Dist: pyyaml
 Requires-Dist: click
+Requires-Dist: pyyaml
 Requires-Dist: Jinja2
 Provides-Extra: django
 Requires-Dist: Django>=4.2; extra == "django"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 code-annotations
 =============================
 
-|pypi-badge| |CI| |codecov-badge| |doc-badge| |pyversions-badge|
-|license-badge|
-
 Extensible tools for parsing annotations in codebases
 
 Overview
@@ -88,31 +99,6 @@ refer to this `list of resources`_ if you need any assistance.
 .. _list of resources: https://open.edx.org/getting-help
 
 
-.. |pypi-badge| image:: https://img.shields.io/pypi/v/code-annotations.svg
-    :target: https://pypi.python.org/pypi/code-annotations/
-    :alt: PyPI
-
-.. |CI| image:: https://github.com/openedx/code-annotations/workflows/Python%20CI/badge.svg?branch=master
-    :target: https://github.com/openedx/code-annotations/actions?query=workflow%3A%22Python+CI%22
-    :alt: CI
-
-.. |codecov-badge| image:: http://codecov.io/github/edx/code-annotations/coverage.svg?branch=master
-    :target: http://codecov.io/github/edx/code-annotations?branch=master
-    :alt: Codecov
-
-.. |doc-badge| image:: https://readthedocs.org/projects/code-annotations/badge/?version=latest
-    :target: http://code-annotations.readthedocs.io/en/latest/
-    :alt: Documentation
-
-.. |pyversions-badge| image:: https://img.shields.io/pypi/pyversions/code-annotations.svg
-    :target: https://pypi.python.org/pypi/code-annotations/
-    :alt: Supported Python versions
-
-.. |license-badge| image:: https://img.shields.io/github/license/edx/code-annotations.svg
-    :target: https://github.com/openedx/code-annotations/blob/master/LICENSE.txt
-    :alt: License
-
-
 Change Log
 ----------
 
@@ -129,10 +115,15 @@ Change Log
 Unreleased
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+[2.2.0] - 2025-01-15
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Add support for optional Open edX Event trigger in-line annotation.
+
 [2.1.0] - 2024-12-12
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* Add support for optional event warning for in-line annotation.
+* Add support for optional Open edX Event warning for in-line annotation.
 
 [2.0.0] - 2024-10-18
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

{code_annotations-2.1.0 → code_annotations-2.3.0}/code_annotations.egg-info/SOURCES.txt

@@ -34,6 +34,15 @@ code_annotations/extensions/__init__.py
 code_annotations/extensions/base.py
 code_annotations/extensions/javascript.py
 code_annotations/extensions/python.py
+code_annotations/report_templates/html/annotation.tpl
+code_annotations/report_templates/html/annotation_data.tpl
+code_annotations/report_templates/html/annotation_list.tpl
+code_annotations/report_templates/html/base.tpl
+code_annotations/report_templates/rst/annotation.tpl
+code_annotations/report_templates/rst/annotation_data.tpl
+code_annotations/report_templates/rst/annotation_group.tpl
+code_annotations/report_templates/rst/annotation_list.tpl
+code_annotations/report_templates/rst/base.tpl
 requirements/base.in
 tests/test_base.py
 tests/test_django_coverage.py

code_annotations-2.3.0/setup.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python
+"""
+Package metadata for code_annotations.
+"""
+
+import os
+import re
+import sys
+
+from setuptools import setup
+
+
+def get_version(*file_paths):
+    """
+    Extract the version string from the file at the given relative path fragments.
+    """
+    filename = os.path.join(os.path.dirname(__file__), *file_paths)
+    version_file = open(filename).read()
+    version_match = re.search(r"^__version__ = ['\"]([^'\"]*)['\"]", version_file, re.M)
+    if version_match:
+        return version_match.group(1)
+    raise RuntimeError("Unable to find version string.")
+
+
+def load_requirements(*requirements_paths):
+    """
+    Load all requirements from the specified requirements files.
+
+    Returns:
+        list: Requirements file relative path strings
+    """
+    requirements = set()
+    for path in requirements_paths:
+        requirements.update(
+            line.split("#")[0].strip()
+            for line in open(path).readlines()
+            if is_requirement(line.strip())
+        )
+    return list(requirements)
+
+
+def is_requirement(line):
+    """
+    Return True if the requirement line is a package requirement.
+
+    Returns:
+        bool: True if the line is not blank, a comment, a URL, or an included file
+    """
+    return not (
+        line == ""
+        or line.startswith("-r")
+        or line.startswith("#")
+        or line.startswith("-e")
+        or line.startswith("git+")
+        or line.startswith("-c")
+    )
+
+
+VERSION = get_version("code_annotations", "__init__.py")
+
+if sys.argv[-1] == "tag":
+    print("Tagging the version on github:")
+    os.system("git tag -a %s -m 'version %s'" % (VERSION, VERSION))
+    os.system("git push --tags")
+    sys.exit()
+
+README = open(os.path.join(os.path.dirname(__file__), "README.rst")).read()
+CHANGELOG = open(os.path.join(os.path.dirname(__file__), "CHANGELOG.rst")).read()
+
+setup(
+    name="code-annotations",
+    version=VERSION,
+    description="""Extensible tools for parsing annotations in codebases""",
+    long_description=README + "\n\n" + CHANGELOG,
+    long_description_content_type="text/x-rst",
+    author="edX",
+    author_email="oscm@edx.org",
+    url="https://github.com/openedx/code-annotations",
+    packages=[
+        "code_annotations",
+    ],
+    entry_points={
+        "console_scripts": [
+            "code_annotations = code_annotations.cli:entry_point",
+        ],
+        "annotation_finder.searchers": [
+            "javascript = code_annotations.extensions.javascript:JavascriptAnnotationExtension",
+            "python = code_annotations.extensions.python:PythonAnnotationExtension",
+        ],
+    },
+    include_package_data=True,
+    install_requires=load_requirements("requirements/base.in"),
+    extras_require={"django": ["Django>=4.2"]},
+    license="Apache Software License 2.0",
+    zip_safe=False,
+    keywords="edx pii code annotations",
+    python_requires=">=3.11",
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Framework :: Django",
+        "Framework :: Django :: 4.2",
+        "Framework :: Django :: 5.2",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: Apache Software License",
+        "Natural Language :: English",
+        "Programming Language :: Python",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+    ],
+)

{code_annotations-2.1.0 → code_annotations-2.3.0}/tests/test_generate_docs.py

@@ -49,6 +49,40 @@ def test_generate_report_simple():
         assert os.path.exists(created_doc)
 
 
+def test_generate_report_simple_html():
+    find_result = call_script(
+        (
+            'static_find_annotations',
+            '--config_file',
+            'tests/test_configurations/.annotations_test_python_only',
+            '--source_path=tests/extensions/python_test_files/simple_success.pyt',
+            '--no_lint',
+        ),
+        delete_test_reports=False)
+
+    assert find_result.exit_code == EXIT_CODE_SUCCESS
+    assert "Writing report..." in find_result.output
+    report_file = get_report_filename_from_output(find_result.output)
+
+    report_result = call_script(
+        (
+            'generate_docs',
+            report_file,
+            '--config_file',
+            'tests/test_configurations/.annotations_test_success_with_report_docs_html',
+            '-vv'
+        ),
+        delete_test_docs=False
+    )
+
+    assert find_result.exit_code == EXIT_CODE_SUCCESS
+    assert "Report rendered in" in report_result.output
+
+    # All file types are created
+    for created_doc in ('test_reports/index.html', 'test_reports/choice-id.html', 'test_reports/annotation-pii.html'):
+        assert os.path.exists(created_doc)
+
+
 def _do_find(source_path, new_report_path):
     """
     Do a static annotation search with report, rename the report to a distinct name.
@@ -167,4 +201,4 @@ def test_generate_report_missing_key():
     ))
 
     assert report_result.exit_code == EXIT_CODE_FAILURE
-    assert "No report_template_dir key in tests/test_configurations/" in report_result.output
+    assert "No rendered_report_source_link_prefix key in" in report_result.output

code_annotations-2.1.0/code_annotations/contrib/config/__init__.py

@@ -1,19 +0,0 @@
-"""
-Expose contrib configuration file paths as Python variables, for use in 3rd-party utilities.
-"""
-import os
-
-import pkg_resources
-
-FEATURE_TOGGLE_ANNOTATIONS_CONFIG_PATH = pkg_resources.resource_filename(
-    "code_annotations",
-    os.path.join("contrib", "config", "feature_toggle_annotations.yaml"),
-)
-SETTING_ANNOTATIONS_CONFIG_PATH = pkg_resources.resource_filename(
-    "code_annotations",
-    os.path.join("contrib", "config", "setting_annotations.yaml"),
-)
-OPENEDX_EVENTS_ANNOTATIONS_CONFIG_PATH = pkg_resources.resource_filename(
-    "code_annotations",
-    os.path.join("contrib", "config", "openedx_events_annotations.yaml"),
-)

code_annotations-2.1.0/setup.py

@@ -1,110 +0,0 @@
-#!/usr/bin/env python
-"""
-Package metadata for code_annotations.
-"""
-
-import os
-import re
-import sys
-
-from setuptools import setup
-
-
-def get_version(*file_paths):
-    """
-    Extract the version string from the file at the given relative path fragments.
-    """
-    filename = os.path.join(os.path.dirname(__file__), *file_paths)
-    version_file = open(filename).read()
-    version_match = re.search(r"^__version__ = ['\"]([^'\"]*)['\"]",
-                              version_file, re.M)
-    if version_match:
-        return version_match.group(1)
-    raise RuntimeError('Unable to find version string.')
-
-
-def load_requirements(*requirements_paths):
-    """
-    Load all requirements from the specified requirements files.
-
-    Returns:
-        list: Requirements file relative path strings
-    """
-    requirements = set()
-    for path in requirements_paths:
-        requirements.update(
-            line.split('#')[0].strip() for line in open(path).readlines()
-            if is_requirement(line.strip())
-        )
-    return list(requirements)
-
-
-def is_requirement(line):
-    """
-    Return True if the requirement line is a package requirement.
-
-    Returns:
-        bool: True if the line is not blank, a comment, a URL, or an included file
-    """
-    return not (
-        line == '' or
-        line.startswith('-r') or
-        line.startswith('#') or
-        line.startswith('-e') or
-        line.startswith('git+') or
-        line.startswith('-c')
-    )
-
-
-VERSION = get_version('code_annotations', '__init__.py')
-
-if sys.argv[-1] == 'tag':
-    print("Tagging the version on github:")
-    os.system("git tag -a %s -m 'version %s'" % (VERSION, VERSION))
-    os.system("git push --tags")
-    sys.exit()
-
-README = open(os.path.join(os.path.dirname(__file__), 'README.rst')).read()
-CHANGELOG = open(os.path.join(os.path.dirname(__file__), 'CHANGELOG.rst')).read()
-
-setup(
-    name='code-annotations',
-    version=VERSION,
-    description="""Extensible tools for parsing annotations in codebases""",
-    long_description=README + '\n\n' + CHANGELOG,
-    long_description_content_type='text/x-rst',
-    author='edX',
-    author_email='oscm@edx.org',
-    url='https://github.com/openedx/code-annotations',
-    packages=[
-        'code_annotations',
-    ],
-    entry_points={
-        'console_scripts': [
-            'code_annotations = code_annotations.cli:entry_point',
-        ],
-        'annotation_finder.searchers': [
-            'javascript = code_annotations.extensions.javascript:JavascriptAnnotationExtension',
-            'python = code_annotations.extensions.python:PythonAnnotationExtension',
-        ],
-    },
-    include_package_data=True,
-    install_requires=load_requirements('requirements/base.in'),
-    extras_require={"django": ["Django>=4.2"]},
-    license="Apache Software License 2.0",
-    zip_safe=False,
-    keywords='edx pii code annotations',
-    python_requires=">=3.11",
-    classifiers=[
-        'Development Status :: 3 - Alpha',
-        'Framework :: Django',
-        'Framework :: Django :: 4.2',
-        'Intended Audience :: Developers',
-        'License :: OSI Approved :: Apache Software License',
-        'Natural Language :: English',
-        'Programming Language :: Python',
-        'Programming Language :: Python :: 3',
-        'Programming Language :: Python :: 3.11',
-        'Programming Language :: Python :: 3.12',
-    ],
-)

{code_annotations-2.1.0 → code_annotations-2.3.0}/code_annotations.egg-info/requires.txt

@@ -1,7 +1,7 @@
 python-slugify
 stevedore
-pyyaml
 click
+pyyaml
 Jinja2
 
 [django]