Package API

Basic usage example

from edulint import check_code

# using default configuration
_config, problems = check_code(["/path/to/file.py"])

# changing configuration; options are treated as if passed through the command line interface
_config, problems = check_code(["/path/to/file.py"], ["config-file=empty", "pylint=--enable=identical-if-branches"])

In each case, variable problems now contains a list of all detected Problem instances.

If the detection does not behave as expected, the first element of the returned tuple (here ignored) contains detailed information on what exact configuration options were used. For the exact structure of the config, refer to check_code.

Warning

Encountered errors are logged to stderr using loguru. By default, the package API uses loguru’s default settings, which also display INFO level logs, which edulint emits frequently. To get rid of these, change the minimal log level or redirect the logs to a different sink.

The following code changes the minimal log level to WARNING. Place it before the first call to check_code to get rid of the INFO logs.

from loguru import logger
import sys

logger.remove()
logger.add(sys.stderr, level="WARNING")

Full reference

class edulint.Arg(option: Option, val: T)

Stores option and its value.

option: Option: For possible options, see Configuration in documentation or the packages help page (edulint check -h).

val: T: Value type depends on the option – different options have different value types.

class edulint.ImmutableConfig(config: Tuple[Arg[bool | Tuple[str, ...] | str | None | int], ...], enablers: Dict[str, str])

Configuration used for file checking.

config: Tuple[Arg[bool | Tuple[str, ...] | str | None | int], ...]: The arguments contained in the configuration.

class edulint.Problem(source: Linter, enabled_by: str | None, path: str, line: int, column: int, code: str, text: str, end_line: int | None = None, end_column: int | None = None, symbol: str | None = None)

Holds a single occurrence of an issue.

code: str: The message id of the issue (e.g., E0213).

column: int: The column where the issue starts.

end_column: int | None = None: The column where the issue ends.

end_line: int | None = None: The line where the issue ends.

line: int: The line where the issue starts.

path: str: File that contains the issue.

source: Linter: Linter that reported the issue.

symbol: str | None = None: The symbolic message id the issue has (e.g., no-self-argument); not set for Flake8 issues.

text: str: The text of the issue.

class edulint.Translation(translation: str, extracts: Dict[str, Dict[str, str]])

Holds information on how to translate a message.

extracts: Dict[str, Dict[str, str]]: Templates for the translations of extracts. Extracts are parts of the message which are filled in dynamically, but which do not contain a code but rather some words in the source language.

translate(code: str, message: str)

Translates passed message using this translation template.

Parameters:

code (str) – the message id of the translated message
message (str) – the text to translate; if the message does not match the expected pattern, the template is returned

translate_extracts(extracts: List[str]) → List[str]

Translates passed extracts.

Parameters:: extracts (List[str]) – the extracts to translate
Returns:: the list of translated extracts; if there is no translation for a given extract, it is passed unchanged
Return type:: List[str]

translation: str: Template for the translated message.

edulint.check_code(files_or_dirs: List[str], options: List[str] | None = None) → Tuple[List[Tuple[List[str], ImmutableConfig, Dict[str, Translation]]], List[Problem]] | None

Analyzes the passed files or directories. If a directory is passed, it recursively walks its sub-directories and analyzes all found .py files.

Parameters:

files_or_dirs (List[str]) – Files or directories to analyze. If the specified path does not exist, it logs a warning to stderr.
options (Optional[List[str]]) – A list of options as specified by the package’s argument OPTION (see edulint check -h for help) (a possible value could be ["pylint=--enable=duplicate-key"])

Returns:

A configurations used for each file and encoutered issues. The first element of the returned tuple is a list of tuples containing three elements: a list of analyzed files, a configuration and message translations – all the files in the list share the configuration and` the translation (remember that different files can be linted using different configurations due to in-file configuration options). The second element of the returned tuple is the list of encountered problems. If an error was encountered, the function returns None.

Return type:

Tuple[List[Tuple[List[str], ImmutableConfig, LangTranslations]], List[Problem]] | None

edulint.get_message_explanations(message_ids: List[str] | None = None) → Dict[str, Dict[str, str]]

Returns explanations for given message ids. If an explanation is requested for a message id that does not have an explanation, the warning is logged to stderr.

Parameters:: message_ids (List[str] | None) – An optional list of message ids to receive explanations for. If None is passed, returns all available explanations.
Returns:: A dictionary with message ids as keys and explanations as values. Each explanations is a dictionary with optional keys “why” and “examples”. “Why” Contains rationale for why the pattern should be avoided. “Examples” contains examples of erroneous and corrected code.
Return type:: Dict[str, Dict[str, str]]