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

{code-annotations-1.7.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.7.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.7.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: python-slugify
-Requires-Dist: click
 Requires-Dist: pyyaml
-Requires-Dist: stevedore
+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.7.0 → code_annotations-2.2.0}/code_annotations/__init__.py

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

{code-annotations-1.7.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.7.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-1.7.0 → code_annotations-2.2.0}/code_annotations/contrib/config/openedx_events_annotations.yaml

@@ -6,12 +6,14 @@ safelist_path: .annotation_safe_list.yml
 coverage_target: 100.0
 annotations:
   feature_toggle:
-    # See annotation format documentation: https://edx-toggles.readthedocs.io/en/latest/how_to/documenting_new_feature_toggles.html
+    # 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

{code-annotations-1.7.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-1.7.0 → code_annotations-2.2.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,47 @@ 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}"]
+                )
+
             subject_header += event_section
 
         if domain_header: