code_annotations package#
Subpackages#
Submodules#
code_annotations.annotation_errors module#
List possible annotation error types.
- code_annotations.annotation_errors.AnnotationErrorType#
alias of
AnnotationError
- code_annotations.annotation_errors.add_error_type(message, symbol, description)#
Create an AnnotationErrorType instance and add it to TYPES.
code_annotations.base module#
Click command to do static annotation searching via Stevedore plugins.
- class code_annotations.base.AnnotationConfig(config_file_path, report_path_override=None, verbosity=1, source_path_override=None)#
Bases:
object
Configuration shared among all Code Annotations commands.
- class code_annotations.base.BaseSearch(config)#
Bases:
object
Base class for searchers.
- check_group(annotations)#
Perform several linting checks on a group of annotations.
The following checks are performed:
Choice fields should have a valid value
Annotation tokens are valid
There is no duplicate
All non-optional tokens are present
- check_results(all_results)#
Spin through all search results, confirm that they all match configuration.
If errors are found they are added to self.errors.
- Parameters:
all_results – Dict of annotations found in search()
- Returns:
Boolean indicating whether or not any errors were found
- format_file_results(all_results, results)#
Add all extensions’ search results for a file to the overall results.
- Parameters:
all_results – Aggregated results to add the results to
results – Results of search() on a single file
- Returns:
None, modifies all_results
- iter_groups(annotations)#
Iterate on groups of annotations.
Annotations are considered as a group when they all have the same line_number and optional extra[‘object_id’]. The line number points to the beginning of the annotation group. The object_id is set mostly for annotations parsed from a safelist.
- Yields:
annotations (annotation list)
- report(all_results, report_prefix='')#
Generate the YAML report of all search results.
- Parameters:
all_results – Dict of found annotations, indexed by filename
report_prefix – Prefix to add to report filename
- Returns:
Filename of generated report
- abstract search()#
Walk the source tree, send known file types to extensions.
- Returns:
annotations} for all files with found annotations.
- Return type:
Dict of {filename
code_annotations.cli module#
Command line interface for code annotation tools.
code_annotations.exceptions module#
Custom exceptions for code_annotations.
code_annotations.find_django module#
Annotation searcher for Django model comment searching Django introspection.
- class code_annotations.find_django.DjangoSearch(config)#
Bases:
BaseSearch
Handles Django model comment searching for annotations.
- check_coverage()#
Perform checking of coverage percentage based on stats collected in setup and search.
- Returns:
- Bool indicating whether or not the number of annotated models covers a percentage
of total models needing annotations greater than or equal to the configured coverage_target.
- static get_model_id(model)#
Construct the django standard model identifier in “app_label.ModelClassName” notation.
- Parameters:
model (django.db.models.Model) – A model for which to create an identifier.
- Returns:
identifier string for the given model.
- Return type:
- static get_models_requiring_annotations()#
Determine all local and non-local models via django model introspection.
Note that non-local models returned may contain 1st party models (authored by edX). This is a compromise in accuracy in order to simplify the generation of this list, and also to ease the transition from zero to 100% annotations in edX satellite repositories.
- Returns:
2-tuple where the first item is a set of local models, and the second item is a set of non-local models.
- Return type:
- static is_non_local(model)#
Determine if the given model is non-local to the current IDA.
Non-local models are all installed models which are not “local”, by definition. “Local” models are installed models which are defined in code which physically lives in the current codebase, where “current codebase” ostensibly refers to the code providing the currently active django project.
- Parameters:
model (django.db.models.Model) – A model to check.
- Returns:
True if the given model is non-local.
- Return type:
- list_local_models()#
Dump a list of models in the local code tree that need annotations to stdout.
- static requires_annotations(model)#
Return true if the given model actually requires annotations, according to PLAT-2344.
- search()#
Introspect the configured Django model docstrings for annotations.
- Returns:
Dict of all found annotations keyed by filename
- seed_safelist()#
Seed a new safelist file with all non-local models that need to be vetted.
- static setup_django()#
Prepare to make django library function calls.
On behalf of the current Django project in the current working directory, setup/load the django framework, specified settings, and apps therein. This should be called before calling any django submodule functions which expect apps to be loaded.
This function is idempotent.
code_annotations.find_static module#
Annotation searcher for static comment searching via Stevedore plugins.
- class code_annotations.find_static.StaticSearch(config)#
Bases:
BaseSearch
Handles static code searching for annotations.
- search()#
Walk the source tree, send known file types to extensions.
- Returns:
Dict of all found annotations keyed by filename
- search_extension(ext, file_handle, file_extensions_map, filename_extension)#
Execute a search on the given file using the given extension.
- Parameters:
ext – Extension to execute the search on
file_handle – An open file handle search
file_extensions_map – Dict mapping of extension names to configured filename extensions
filename_extension – The filename extension of the file being searched
- Returns:
Tuple of (extension name, list of found annotation dicts)
code_annotations.generate_docs module#
Contains functionality for turning YAML reports into human-readable documentation.
code_annotations.helpers module#
Helpers for code_annotations scripts.
- class code_annotations.helpers.VerboseEcho#
Bases:
object
Helper to handle verbosity-dependent logging.
- echo(output, verbosity_level=0, **kwargs)#
Echo the given output, if over the verbosity threshold.
- Parameters:
output – Text to output
verbosity_level – Only output if our verbosity level is >= this.
kwargs – Any additional keyword args to pass to click.echo
- echo_v(output, **kwargs)#
Echo the given output if verbosity level is >= 1.
- Parameters:
output – Text to output
kwargs – Any additional keyword args to pass to click.echo
- echo_vv(output, **kwargs)#
Echo the given output if verbosity level is >= 2.
- Parameters:
output – Text to output
kwargs – Any additional keyword args to pass to click.echo
- echo_vvv(output, **kwargs)#
Echo the given output if verbosity level is >= 3.
- Parameters:
output – Text to output
kwargs – Any additional keyword args to pass to click.echo
- pprint(data, indent=4, verbosity_level=0)#
Pretty-print some data with the given verbosity level.
- set_verbosity(verbosity)#
Override the default verbosity level.
- Parameters:
verbosity – The verbosity level to set to
kwargs – Any additional keyword args to pass to click.echo
- verbosity = 1#
- code_annotations.helpers.clean_abs_path(filename_to_clean, parent_path)#
Safely strips the parent path from the given filename, leaving only the relative path.
- Parameters:
filename_to_clean – Input filename
parent_path – Path to remove from the input
- Returns:
Updated path
- code_annotations.helpers.clean_annotation(token, data)#
Clean annotation token and data by stripping all trailing/prefix empty spaces.
- code_annotations.helpers.fail(msg)#
Log the message and exit.
- Parameters:
msg – Message to log
- code_annotations.helpers.get_annotation_regex(annotation_regexes)#
Return the full regex to search inside comments for configured annotations.
A successful match against the regex will return two groups of interest: ‘token’ and ‘data’.
This regular expression supports annotation tokens that span multiple lines. To do so, prefix each line after the first by at least two leading spaces. E.g:
Unfortunately, the indenting spaces will find their way to the content of the “token” group.
- Parameters:
annotation_regexes – List of re.escaped annotation tokens to search for.
- Returns:
Regex ready for searching comments for annotations.
Module contents#
Extensible tools for parsing annotations in codebases.