code-annotations 1.6.0__tar.gz → 2.2.0__tar.gz

{code-annotations-1.6.0 → code_annotations-2.2.0}/CHANGELOG.rst

@@ -14,6 +14,34 @@ 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 Open edX Event warning for in-line annotation.
+
+[2.0.0] - 2024-10-18
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Drop support for python 3.8
+* Adds support for python 3.11 & 3.12
+
+[1.8.1] - 2024-07-11
+~~~~~~~~~~~~~~~~~~~~
+
+* Fix elapsed-time calculations to always use UTC. Other clocks can be altered partway through by Django config settings being loaded while the timer is running, resulting in reporting elapsed time of "-17999.895582 seconds" or similar.
+* Fix report filename to use year-month-day order, not year-day-month. (Also more compact, now.)
+
+[1.8.0] - 2024-03-31
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Added python3.11 and 3.12 support. Dropped django32 support.
+
+
 [1.6.0] - 2024-01-31
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

{code-annotations-1.6.0 → code_annotations-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: code-annotations
-Version: 1.6.0
+Version: 2.2.0
 Summary: Extensible tools for parsing annotations in codebases
 Home-page: https://github.com/openedx/code-annotations
 Author: edX
@@ -9,24 +9,37 @@ License: Apache Software License 2.0
 Keywords: edx pii code annotations
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: Django
-Classifier: Framework :: Django :: 3.2
 Classifier: Framework :: Django :: 4.2
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Natural Language :: English
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
 License-File: NOTICE.txt
-Requires-Dist: stevedore
-Requires-Dist: python-slugify
-Requires-Dist: click
 Requires-Dist: pyyaml
+Requires-Dist: click
 Requires-Dist: Jinja2
+Requires-Dist: stevedore
+Requires-Dist: python-slugify
 Provides-Extra: django
-Requires-Dist: Django<2.3,>=2.2; 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: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 code-annotations
 =============================
@@ -128,6 +141,34 @@ 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 Open edX Event warning for in-line annotation.
+
+[2.0.0] - 2024-10-18
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Drop support for python 3.8
+* Adds support for python 3.11 & 3.12
+
+[1.8.1] - 2024-07-11
+~~~~~~~~~~~~~~~~~~~~
+
+* Fix elapsed-time calculations to always use UTC. Other clocks can be altered partway through by Django config settings being loaded while the timer is running, resulting in reporting elapsed time of "-17999.895582 seconds" or similar.
+* Fix report filename to use year-month-day order, not year-day-month. (Also more compact, now.)
+
+[1.8.0] - 2024-03-31
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Added python3.11 and 3.12 support. Dropped django32 support.
+
+
 [1.6.0] - 2024-01-31
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

{code-annotations-1.6.0 → code_annotations-2.2.0}/code_annotations/__init__.py

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

{code-annotations-1.6.0 → code_annotations-2.2.0}/code_annotations/base.py

@@ -616,9 +616,9 @@ class BaseSearch(metaclass=ABCMeta):
         """
         self.echo.echo_vv(yaml.dump(all_results, default_flow_style=False))
 
-        now = datetime.datetime.now()
+        now = datetime.datetime.utcnow()
         report_filename = os.path.join(self.config.report_path, '{}{}.yaml'.format(
-            report_prefix, now.strftime('%Y-%d-%m-%H-%M-%S')
+            report_prefix, now.strftime('%Y%m%d-%H%M%S')
         ))
 
         formatted_results = self._format_results_for_report(all_results)

{code-annotations-1.6.0 → code_annotations-2.2.0}/code_annotations/cli.py

@@ -1,6 +1,7 @@
 """
 Command line interface for code annotation tools.
 """
+
 import datetime
 import sys
 import traceback
@@ -21,53 +22,88 @@ def entry_point():
     """
 
 
-@entry_point.command('django_find_annotations')
+@entry_point.command("django_find_annotations")
+@click.option(
+    "--config_file",
+    default=".annotations",
+    help="Path to the configuration file",
+    type=click.Path(exists=True, dir_okay=False, resolve_path=True),
+)
+@click.option(
+    "--seed_safelist/--no_safelist",
+    default=False,
+    show_default=True,
+    help="Generate an initial safelist file based on the current Django environment.",
+)
+@click.option(
+    "--list_local_models/--no_list_models",
+    default=False,
+    show_default=True,
+    help="List all locally defined models (in the current repo) that require annotations.",
+)
+@click.option(
+    "--app_name",
+    default=None,
+    help="(Optional) App name for which coverage is generated.",
+)
+@click.option("--report_path", default=None, help="Location to write the report")
+@click.option("-v", "--verbosity", count=True, help="Verbosity level (-v through -vvv)")
 @click.option(
-    '--config_file',
-    default='.annotations',
-    help='Path to the configuration file',
-    type=click.Path(exists=True, dir_okay=False, resolve_path=True)
+    "--lint/--no_lint",
+    help="Enable or disable linting checks",
+    default=False,
+    show_default=True,
 )
 @click.option(
-    '--seed_safelist/--no_safelist',
+    "--report/--no_report",
+    help="Enable or disable writing the report",
     default=False,
     show_default=True,
-    help='Generate an initial safelist file based on the current Django environment.',
 )
 @click.option(
-    '--list_local_models/--no_list_models',
+    "--coverage/--no_coverage",
+    help="Enable or disable coverage checks",
     default=False,
     show_default=True,
-    help='List all locally defined models (in the current repo) that require annotations.',
 )
-@click.option('--app_name', default='', help='(Optional) App name for which coverage is generated.')
-@click.option('--report_path', default=None, help='Location to write the report')
-@click.option('-v', '--verbosity', count=True, help='Verbosity level (-v through -vvv)')
-@click.option('--lint/--no_lint', help='Enable or disable linting checks', default=False, show_default=True)
-@click.option('--report/--no_report', help='Enable or disable writing the report', default=False, show_default=True)
-@click.option('--coverage/--no_coverage', help='Enable or disable coverage checks', default=False, show_default=True)
 def django_find_annotations(
-        config_file,
-        seed_safelist,
-        list_local_models,
-        app_name,
-        report_path,
-        verbosity,
-        lint,
-        report,
-        coverage
+    config_file,
+    seed_safelist,
+    list_local_models,
+    app_name,
+    report_path,
+    verbosity,
+    lint,
+    report,
+    coverage,
 ):
     """
     Subcommand for dealing with annotations in Django models.
     """
     try:
-        start_time = datetime.datetime.now()
+        start_time = datetime.datetime.utcnow()
+
+        if (
+            not coverage
+            and not seed_safelist
+            and not list_local_models
+            and not lint
+            and not report
+        ):
+            click.echo(
+                "No actions specified. Please specify one or more of --seed_safelist, --list_local_models, "
+                "--lint, --report, or --coverage"
+            )
+            sys.exit(1)
+
         config = AnnotationConfig(config_file, report_path, verbosity)
-        searcher = DjangoSearch(config)
+        searcher = DjangoSearch(config, app_name)
 
         # Early out if we're trying to do coverage, but a coverage target is not configured
         if coverage and not config.coverage_target:
-            raise ConfigurationException("Please add 'coverage_target' to your configuration before running --coverage")
+            raise ConfigurationException(
+                "Please add 'coverage_target' to your configuration before running --coverage"
+            )
 
         if seed_safelist:
             searcher.seed_safelist()
@@ -106,38 +142,51 @@ def django_find_annotations(
             for filename in annotated_models:
                 annotation_count += len(annotated_models[filename])
 
-            elapsed = datetime.datetime.now() - start_time
-            click.echo("Search found {} annotations in {} seconds.".format(
-                annotation_count, elapsed.total_seconds()
-            ))
-
-    except Exception as exc:  # pylint: disable=broad-except
+            elapsed = datetime.datetime.utcnow() - start_time
+            click.echo(
+                "Search found {} annotations in {} seconds.".format(
+                    annotation_count, elapsed.total_seconds()
+                )
+            )
+    except Exception as exc:
         click.echo(traceback.print_exc())
         fail(str(exc))
 
 
-@entry_point.command('static_find_annotations')
+@entry_point.command("static_find_annotations")
 @click.option(
-    '--config_file',
-    default='.annotations',
-    help='Path to the configuration file',
-    type=click.Path(exists=True, dir_okay=False, resolve_path=True)
+    "--config_file",
+    default=".annotations",
+    help="Path to the configuration file",
+    type=click.Path(exists=True, dir_okay=False, resolve_path=True),
 )
 @click.option(
-    '--source_path',
-    help='Location of the source code to search',
-    type=click.Path(exists=True, dir_okay=True, resolve_path=True)
+    "--source_path",
+    help="Location of the source code to search",
+    type=click.Path(exists=True, dir_okay=True, resolve_path=True),
 )
-@click.option('--report_path', default=None, help='Location to write the report')
-@click.option('-v', '--verbosity', count=True, help='Verbosity level (-v through -vvv)')
-@click.option('--lint/--no_lint', help='Enable or disable linting checks', default=True, show_default=True)
-@click.option('--report/--no_report', help='Enable or disable writing the report file', default=True, show_default=True)
-def static_find_annotations(config_file, source_path, report_path, verbosity, lint, report):
+@click.option("--report_path", default=None, help="Location to write the report")
+@click.option("-v", "--verbosity", count=True, help="Verbosity level (-v through -vvv)")
+@click.option(
+    "--lint/--no_lint",
+    help="Enable or disable linting checks",
+    default=True,
+    show_default=True,
+)
+@click.option(
+    "--report/--no_report",
+    help="Enable or disable writing the report file",
+    default=True,
+    show_default=True,
+)
+def static_find_annotations(
+    config_file, source_path, report_path, verbosity, lint, report
+):
     """
     Subcommand to find annotations via static file analysis.
     """
     try:
-        start_time = datetime.datetime.now()
+        start_time = datetime.datetime.utcnow()
         config = AnnotationConfig(config_file, report_path, verbosity, source_path)
         searcher = StaticSearch(config)
         all_results = searcher.search()
@@ -161,7 +210,7 @@ def static_find_annotations(config_file, source_path, report_path, verbosity, li
             report_filename = searcher.report(all_results)
             click.echo(f"Report written to {report_filename}.")
 
-        elapsed = datetime.datetime.now() - start_time
+        elapsed = datetime.datetime.utcnow() - start_time
         annotation_count = 0
 
         for filename in all_results:
@@ -169,49 +218,49 @@ def static_find_annotations(config_file, source_path, report_path, verbosity, li
 
         click.echo(f"Search found {annotation_count} annotations in {elapsed}.")
 
-    except Exception as exc:  # pylint: disable=broad-except
+    except Exception as exc:
         click.echo(traceback.print_exc())
         fail(str(exc))
 
 
 @entry_point.command("generate_docs")
 @click.option(
-    '--config_file',
-    default='.annotations',
-    help='Path to the configuration file',
-    type=click.Path(exists=True, dir_okay=False)
+    "--config_file",
+    default=".annotations",
+    help="Path to the configuration file",
+    type=click.Path(exists=True, dir_okay=False),
 )
-@click.option('-v', '--verbosity', count=True, help='Verbosity level (-v through -vvv)')
-@click.argument("report_files", type=click.File('r'), nargs=-1)
-def generate_docs(
-        config_file,
-        verbosity,
-        report_files
-):
+@click.option("-v", "--verbosity", count=True, help="Verbosity level (-v through -vvv)")
+@click.argument("report_files", type=click.File("r"), nargs=-1)
+def generate_docs(config_file, verbosity, report_files):
     """
     Generate documentation from a code annotations report.
     """
-    start_time = datetime.datetime.now()
+    start_time = datetime.datetime.utcnow()
 
     try:
         config = AnnotationConfig(config_file, verbosity)
 
         for key in (
-                'report_template_dir',
-                'rendered_report_dir',
-                'rendered_report_file_extension',
-                'rendered_report_source_link_prefix'
+            "report_template_dir",
+            "rendered_report_dir",
+            "rendered_report_file_extension",
+            "rendered_report_source_link_prefix",
         ):
             if not getattr(config, key):
                 raise ConfigurationException(f"No {key} key in {config_file}")
 
-        config.echo("Rendering the following reports: \n{}".format("\n".join([r.name for r in report_files])))
+        config.echo(
+            "Rendering the following reports: \n{}".format(
+                "\n".join([r.name for r in report_files])
+            )
+        )
 
         renderer = ReportRenderer(config, report_files)
         renderer.render()
 
-        elapsed = datetime.datetime.now() - start_time
+        elapsed = datetime.datetime.utcnow() - start_time
         click.echo(f"Report rendered in {elapsed.total_seconds()} seconds.")
-    except Exception as exc:  # pylint: disable=broad-except
+    except Exception as exc:
         click.echo(traceback.print_exc())
         fail(str(exc))

code_annotations-2.2.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.2.0/code_annotations/contrib/config/openedx_events_annotations.yaml

@@ -0,0 +1,20 @@
+# This code-annotations configuration file supports openedx-events
+
+source_path: ./
+report_path: reports
+safelist_path: .annotation_safe_list.yml
+coverage_target: 100.0
+annotations:
+  feature_toggle:
+    # See annotation format documentation: https://docs.openedx.org/projects/openedx-events/en/latest/reference/in-line-code-annotations-for-an-event.html
+    - ".. event_type:":
+    - ".. event_name:":
+    - ".. event_description:":
+    - ".. event_data:":
+    - ".. event_key_field:":
+    - ".. event_trigger_repository:":
+    - ".. event_warning:":
+extensions:
+    python:
+        - py
+rst_template: doc.rst.j2

{code-annotations-1.6.0 → code_annotations-2.2.0}/code_annotations/contrib/sphinx/extensions/featuretoggles.py

@@ -111,7 +111,7 @@ class FeatureToggles(SphinxDirective):
             for opt in optional_attrs:
                 if toggle.get(f".. toggle_{opt}:") not in (None, "None", "n/a", "N/A"):
                     toggle_section += nodes.paragraph(
-                        text=f'{opt.title().replace("_"," ")}: {toggle[f".. toggle_{opt}:"]}',
+                        text=f'{opt.title().replace("_", " ")}: {toggle[f".. toggle_{opt}:"]}',
                         ids=[f"{opt}-{toggle_name}"],
                     )
             yield toggle_section

code_annotations-2.2.0/code_annotations/contrib/sphinx/extensions/openedx_events.py

@@ -0,0 +1,182 @@
+"""
+Sphinx extension for viewing openedx events annotations.
+"""
+import os
+
+from docutils import nodes
+from sphinx.util.docutils import SphinxDirective
+
+from code_annotations.contrib.config import OPENEDX_EVENTS_ANNOTATIONS_CONFIG_PATH
+
+from .base import find_annotations
+
+
+def find_events(source_path):
+    """
+    Find the events as defined in the configuration file.
+
+    Return:
+        events (dict): found events indexed by event type.
+    """
+    return find_annotations(
+        source_path, OPENEDX_EVENTS_ANNOTATIONS_CONFIG_PATH, ".. event_type:"
+    )
+
+
+class OpenedxEvents(SphinxDirective):
+    """
+    Sphinx directive to list the events in a single documentation page.
+
+    Use this directive as follows::
+
+        .. openedxevents::
+
+    This directive supports the following configuration parameters:
+
+    - ``openedxevents_source_path``: absolute path to the repository file tree. E.g:
+
+        openedxevents_source_path = os.path.join(os.path.dirname(__file__), "..", "..")
+
+    - ``openedxevents_repo_url``: Github repository where the code is hosted. E.g:
+
+        openedxevents_repo_url = "https://github.com/openedx/myrepo"
+
+    - ``openedxevents_repo_version``: current version of the git repository. E.g:
+
+        import git
+        try:
+            repo = git.Repo(search_parent_directories=True)
+            openedxevents_repo_version = repo.head.object.hexsha
+        except git.InvalidGitRepositoryError:
+            openedxevents_repo_version = "main"
+    """
+
+    required_arguments = 0
+    optional_arguments = 0
+    option_spec = {}
+
+    def run(self):
+        """
+        Public interface of the Directive class.
+
+        Return:
+            nodes (list): nodes to be appended to the resulting document.
+        """
+        return list(self.iter_nodes())
+
+    def iter_nodes(self):
+        """
+        Iterate on the docutils nodes generated by this directive.
+        """
+        events = find_events(self.env.config.openedxevents_source_path)
+
+        current_domain = ""
+        domain_header = None
+        current_subject = ""
+        subject_header = None
+
+        for event_type in sorted(events):
+            domain = event_type.split(".")[2]
+            subject = event_type.split(".")[3]
+            if domain != current_domain:
+                if domain_header:
+                    yield domain_header
+
+                current_domain = domain
+                domain_header = nodes.section("", ids=[f"openedxevent-domain-{domain}"])
+                domain_header += nodes.title(text=f"Architectural subdomain: {domain}")
+            if subject != current_subject:
+                current_subject = subject
+                subject_header = nodes.section("", ids=[f"openedxevent-subject"
+                                                        f"-{subject}"])
+                subject_header += nodes.title(text=f"Subject: {subject}")
+                domain_header += subject_header
+
+            event = events[event_type]
+            event_name = event[".. event_name:"]
+            event_name_literal = nodes.literal(text=event_name)
+            event_data = event[".. event_data:"]
+            event_data_literal = nodes.literal(text=event_data)
+            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}"])
+            event_section += nodes.paragraph(text=f"Description: "
+                                                  f"{event_description}")
+            event_section += nodes.paragraph("", "Signal name: ", event_name_literal)
+            if event_key_field:
+                event_section += nodes.paragraph(
+                    "",
+                    "Event key field: ",
+                    event_key_literal
+                )
+            event_section += nodes.paragraph("", "Event data: ", event_data_literal)
+            event_section += nodes.paragraph(
+                "",
+                "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}"]
+                )
+
+            subject_header += event_section
+
+        if domain_header:
+            yield domain_header
+
+
+def setup(app):
+    """
+    Declare the Sphinx extension.
+    """
+    app.add_config_value(
+        "openedxevents_source_path",
+        os.path.abspath(".."),
+        "env",
+    )
+    app.add_config_value("openedxevents_repo_url", "", "env")
+    app.add_config_value("openedxevents_repo_version", "main", "env")
+    app.add_directive("openedxevents", OpenedxEvents)
+
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }