rstcheck_core package

Submodules

rstcheck_core.checker module

rstcheck_core.checker.check_file(source_file, rstcheck_config, overwrite_with_file_config=True)[source]

Check the given file for issues.

On every call docutils’ caches for roles and directives are cleared by reloading their modules.

Parameters:

  • source_file (Path) – Path to file to check

  • rstcheck_config (RstcheckConfig) – Main configuration of the application

  • overwrite_with_file_config (bool) – If the loaded file config should overwrite the rstcheck_config; defaults to True

Return type:

List[LintError]

Returns:

A list of found issues

rstcheck_core.checker.check_source(source, source_file=None, ignores=None, report_level=ReportLevel.INFO, warn_unknown_settings=False)[source]

Check the given rst source for issues.

Parameters:
Return type:

Generator[LintError, None, None]

Returns:

None

Yield:

Found issues

class rstcheck_core.checker.CodeBlockChecker(source_origin, ignores=None, report_level=ReportLevel.INFO, warn_unknown_settings=False)[source]

Bases: object

Checker for code blockes with different languages.

Inititalize CodeBlockChecker.

Parameters:
language_is_supported(language)[source]

Check if given language can be checked.

Parameters:

language (str) – Language to check

Return type:

bool

Returns:

If langauge can be checked

create_checker(source_code, language)[source]

Create a checker function for the given source and language.

Parameters:

  • source – Source code to check

  • language (str) – Language of the source code

  • source_code (str) –

Return type:

Callable[..., Generator[LintError, None, None]]

Returns:

Checker function

check(source_code, language)[source]

Call the appropiate checker function for the given langauge to check given source.

Parameters:

  • source – Source code to check

  • language (str) – Language of the source code

  • source_code (str) –

Return type:

Generator[LintError, None, None]

Returns:

None if language is not supported

Yield:

Found issues

check_python(source_code)[source]

Check python source for syntax errors.

Parameters:

  • source – Python source code to check

  • source_code (str) –

Return type:

Generator[LintError, None, None]

Returns:

None

Yield:

Found issues

check_json(source_code)[source]

Check JSON source for syntax errors.

Parameters:

  • source – JSON source code to check

  • source_code (str) –

Return type:

Generator[LintError, None, None]

Returns:

None

Yield:

Found issues

check_xml(source_code)[source]

Check XML source for syntax errors.

Parameters:

  • source – XML source code to check

  • source_code (str) –

Return type:

Generator[LintError, None, None]

Returns:

None

Yield:

Found issues

check_rst(source_code)[source]

Check nested rst source for syntax errors.

Parameters:

  • source – rst source code to check

  • source_code (str) –

Return type:

Generator[LintError, None, None]

Returns:

None

Yield:

Found issues

check_doctest(source_code)[source]

Check doctest source for syntax errors.

This does not run the test as that would be unsafe. Nor does this check the Python syntax in the doctest. That could be purposely incorrect for testing purposes.

Parameters:

  • source – XML source code to check

  • source_code (str) –

Return type:

Generator[LintError, None, None]

Returns:

None

Yield:

Found issues

check_bash(source_code)[source]

Check bash source for syntax errors.

Parameters:

  • source – bash source code to check

  • source_code (str) –

Return type:

Generator[LintError, None, None]

Returns:

None

Yield:

Found issues

check_c(source_code)[source]

Check C source for syntax errors.

Parameters:

  • source – C source code to check

  • source_code (str) –

Return type:

Generator[LintError, None, None]

Returns:

None

Yield:

Found issues

check_cpp(source_code)[source]

Check C++ source for syntax errors.

Parameters:

  • source – C++ source code to check

  • source_code (str) –

Return type:

Generator[LintError, None, None]

Returns:

None

Yield:

Found issues

rstcheck_core.config module

rstcheck_core.config.CONFIG_FILES = ['.rstcheck.cfg', 'setup.cfg']

Supported default config files.

class rstcheck_core.config.ReportLevel(value)[source]

Bases: Enum

Report levels supported by docutils.

INFO = 1
WARNING = 2
ERROR = 3
SEVERE = 4
NONE = 5
rstcheck_core.config.ReportLevelMap = {'error': 3, 'info': 1, 'none': 5, 'severe': 4, 'warning': 2}

Map docutils report levels in text form to numbers.

rstcheck_core.config.DEFAULT_REPORT_LEVEL = ReportLevel.INFO

Default report level.

class rstcheck_core.config.RstcheckConfigFile(**data)[source]

Bases: BaseModel

Rstcheck config file.

Raises:
Parameters:

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

report_level: Optional[ReportLevel]
ignore_directives: Optional[List[str]]
ignore_roles: Optional[List[str]]
ignore_substitutions: Optional[List[str]]
ignore_languages: Optional[List[str]]
ignore_messages: Optional[Pattern]
classmethod valid_report_level(value)[source]

Validate the report_level setting.

Parameters:

value (Any) – Value to validate

Raises:

ValueError – If value is not a valid docutils report level

Return type:

Optional[ReportLevel]

Returns:

Instance of ReportLevel or None if emptry string.

classmethod split_str(value)[source]

Validate and parse the following ignore_* settings.

  • ignore_directives

  • ignore_roles

  • ignore_substitutions

  • ignore_languages

Comma separated strings are split into a list.

Parameters:

value (Any) – Value to validate

Raises:

ValueError – If not a str or list of str

Return type:

Optional[List[str]]

Returns:

List of things to ignore in the respective category

classmethod join_regex_str(value)[source]

Validate and concatenate the ignore_messages setting to a RegEx string.

If a list ist given, the entries are concatenated with “|” to create an or RegEx.

Parameters:

value (Any) – Value to validate

Raises:

ValueError – If not a str or list of str

Return type:

Union[str, Pattern[str], None]

Returns:

A RegEx string with messages to ignore or typing.Pattern if it is one already

class rstcheck_core.config.RstcheckConfig(**data)[source]

Bases: RstcheckConfigFile

Rstcheck config.

Raises:
Parameters:

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

config_path: Optional[Path]
recursive: Optional[bool]
warn_unknown_settings: Optional[bool]
rstcheck_core.config.load_config_file(file_path, *, log_missing_section_as_warning=True, warn_unknown_settings=False)[source]

Load, parse and validate rstcheck config from a file.

Caution

If a TOML file is passed this function need tomli installed for python versions before 3.11! Use toml extra or install manually.

Parameters:

  • file_path (Path) – File to load config from

  • log_missing_section_as_warning (bool) – If a missing config section should be logged at WARNING (True) or INFO (False) level; defaults to True

  • warn_unknown_settings (bool) – If a warning should be logged for unknown settings in config file; defaults to False

Raises:

FileNotFoundError – If the file is not found

Return type:

Optional[RstcheckConfigFile]

Returns:

instance of RstcheckConfigFile or None on missing config section or NONE is passed as the config path.

rstcheck_core.config.load_config_file_from_dir(dir_path, *, log_missing_section_as_warning=False, warn_unknown_settings=False)[source]

Search, load, parse and validate rstcheck config from a directory.

Searches files from CONFIG_FILES in the directory. If a file is found, try to load the config from it. If is has no config, search further.

Parameters:

  • dir_path (Path) – Directory to search

  • log_missing_section_as_warning (bool) – If a missing config section in a config file should be logged at WARNING (True) or INFO (False) level; defaults to False

  • warn_unknown_settings (bool) – If a warning should be logged for unknown settings in config file; defaults to False

Return type:

Optional[RstcheckConfigFile]

Returns:

instance of RstcheckConfigFile or None if no file is found or no file has a rstcheck section or NONE is passed as the config path.

rstcheck_core.config.load_config_file_from_dir_tree(dir_path, *, log_missing_section_as_warning=False, warn_unknown_settings=False)[source]

Search, load, parse and validate rstcheck config from a directory tree.

Searches files from CONFIG_FILES in the directory. If a file is found, try to load the config from it. If is has no config, search further. If no config is found in the directory search its parents one by one.

Parameters:

  • dir_path (Path) – Directory to search

  • log_missing_section_as_warning (bool) – If a missing config section in a config file should be logged at WARNING (True) or INFO (False) level; defaults to False

  • warn_unknown_settings (bool) – If a warning should be logged for unknown settings in config file; defaults to False

Return type:

Optional[RstcheckConfigFile]

Returns:

instance of RstcheckConfigFile or None if no file is found or no file has a rstcheck section or NONE is passed as the config path.

rstcheck_core.config.load_config_file_from_path(path, *, search_dir_tree=False, log_missing_section_as_warning_for_file=True, log_missing_section_as_warning_for_dir=False, warn_unknown_settings=False)[source]

Analyse the path and call the correct config file loader.

Parameters:

  • path (Path) – Path to load config file from; can be a file or directory

  • search_dir_tree (bool) – If the directory tree should be searched; only applies if path is a directory; defaults to False

  • log_missing_section_as_warning_for_file (bool) – If a missing config section in a config file should be logged at WARNING (True) or INFO (False) level when the given path is a file; defaults to True

  • log_missing_section_as_warning_for_dir (bool) – If a missing config section in a config file should be logged at WARNING (True) or INFO (False) level when the given file is a direcotry; defaults to False

  • warn_unknown_settings (bool) – If a warning should be logged for unknown settings in config file; defaults to False

Raises:

FileNotFoundError – When the passed path is not found.

Return type:

Optional[RstcheckConfigFile]

Returns:

instance of RstcheckConfigFile or None if no file is found or no file has a rstcheck section or NONE is passed as the config path.

rstcheck_core.config.merge_configs(config_base, config_add, *, config_add_is_dominant=True)[source]

Merge two configs into a new one.

Parameters:
Return type:

RstcheckConfig

Returns:

New merged config

rstcheck_core.inline_config module

rstcheck_core.inline_config.get_inline_config_from_source(source, source_origin, warn_unknown_settings=False)[source]

Get rstcheck inline configs from source.

Unknown configs are ignored.

Parameters:

  • source (str) – Source to get config from

  • source_origin (Union[Path, Literal['<string>'], Literal['<stdin>']]) – Origin of the source with the inline ignore comments

  • warn_unknown_settings (bool) – If a warning should be logged on unknown settings; defaults to False

Return type:

List[InlineConfig]

Returns:

A list of inline configs

rstcheck_core.inline_config.find_ignored_directives(source, source_origin, warn_unknown_settings=False)[source]

Search the rst source for rstcheck inline ignore-directives comments.

Directives are ignored via comment.

For example, to ignore directive1, directive2, and directive3:

>>> list(find_ignored_directives('''
... Example
... =======
...
... .. rstcheck: ignore-directives=directive1,directive3
...
... .. rstcheck: ignore-directives=directive2
... ''', "<string>"))
['directive1', 'directive3', 'directive2']
Parameters:

  • source (str) – Rst source code

  • source_origin (Union[Path, Literal['<string>'], Literal['<stdin>']]) – Origin of the source with the inline ignore comments

  • warn_unknown_settings (bool) –

Return type:

Generator[str, None, None]

Returns:

None

Yield:

Found directives to ignore

rstcheck_core.inline_config.find_ignored_roles(source, source_origin, warn_unknown_settings=False)[source]

Search the rst source for rstcheck inline ignore-roles comments.

Roles are ignored via comment.

For example, to ignore role1, role2, and role3:

>>> list(find_ignored_roles('''
... Example
... =======
...
... .. rstcheck: ignore-roles=role1,role3
...
... .. rstcheck: ignore-roles=role2
... ''', "<string>"))
['role1', 'role3', 'role2']
Parameters:

  • source (str) – Rst source code

  • source_origin (Union[Path, Literal['<string>'], Literal['<stdin>']]) – Origin of the source with the inline ignore comments

  • warn_unknown_settings (bool) –

Return type:

Generator[str, None, None]

Returns:

None

Yield:

Found roles to ignore

rstcheck_core.inline_config.find_ignored_substitutions(source, source_origin, warn_unknown_settings=False)[source]

Search the rst source for rstcheck inline ignore-substitutions comments.

Substitutions are ignored via comment.

For example, to ignore substitution1, substitution2, and substitution3:

>>> list(find_ignored_substitutions('''
... Example
... =======
...
... .. rstcheck: ignore-substitutions=substitution1,substitution3
...
... .. rstcheck: ignore-substitutions=substitution2
... ''', "<string>"))
['substitution1', 'substitution3', 'substitution2']
Parameters:

  • source (str) – Rst source code

  • source_origin (Union[Path, Literal['<string>'], Literal['<stdin>']]) – Origin of the source with the inline ignore comments

  • warn_unknown_settings (bool) –

Return type:

Generator[str, None, None]

Returns:

None

Yield:

Found substitutions to ignore

rstcheck_core.inline_config.find_ignored_languages(source, source_origin, warn_unknown_settings=False)[source]

Search the rst source for rstcheck inline ignore-languages comments.

Languages are ignored via comment.

For example, to ignore C++, JSON, and Python:

>>> list(find_ignored_languages('''
... Example
... =======
...
... .. rstcheck: ignore-languages=cpp,json
...
... .. rstcheck: ignore-languages=python
... ''', "<string>"))
['cpp', 'json', 'python']
Parameters:

  • source (str) – Rst source code

  • source_origin (Union[Path, Literal['<string>'], Literal['<stdin>']]) – Origin of the source with the inline ignore comments

  • warn_unknown_settings (bool) –

Return type:

Generator[str, None, None]

Returns:

None

Yield:

Found languages to ignore

rstcheck_core.inline_config.get_inline_flow_control_from_source(source, source_origin, warn_unknown_settings=False)[source]

Get rstcheck inline flow control from source.

Unknown flow controls are ignored.

Parameters:

  • source (str) – Source to get config from

  • source_origin (Union[Path, Literal['<string>'], Literal['<stdin>']]) – Origin of the source with the inline flow control

  • warn_unknown_settings (bool) – If a warning should be logged on unknown settings; defaults to False

Return type:

List[InlineFlowControl]

Returns:

A list of inline flow controls

rstcheck_core.inline_config.find_code_block_ignore_lines(source, source_origin, warn_unknown_settings=False)[source]

Get lines of ignore-next-code-block flow control comments.

Parameters:

  • source (str) – Source to get config from

  • source_origin (Union[Path, Literal['<string>'], Literal['<stdin>']]) – Origin of the source with the inline ignore comments

  • warn_unknown_settings (bool) – If a warning should be logged on unknown settings; defaults to False

Return type:

Generator[int, None, None]

Returns:

None

Yield:

Single values for the target_config

rstcheck_core.runner module

class rstcheck_core.runner.RstcheckMainRunner(check_paths, rstcheck_config, overwrite_config=True)[source]

Bases: object

Main runner of rstcheck_core.

Initialize the RstcheckMainRunner with a base config.

Parameters:

  • check_paths (List[Path]) – Files to check.

  • rstcheck_config (RstcheckConfig) – Base configuration config from e.g. the CLI.

  • overwrite_config (bool) – If file config overwrites current config; defaults to True

property files_to_check: List[Path]

List of files to check.

This list is updated via the RstcheckMainRunner.update_file_list() method.

property nonexisting_paths: List[Path]

List of paths which do not exist.

This list is updated via the RstcheckMainRunner.update_file_list() method.

load_config_file(config_path, warn_unknown_settings=False)[source]

Load config from file and merge with current config.

If the loaded file config overwrites the current config depends on the self.overwrite_config attribute set on initialization.

Parameters:

  • config_path (Path) – Path to config file; can be directory or file

  • warn_unknown_settings (bool) – If a warning should be logged for unknown settings in config file; defaults to False

Return type:

None

update_file_list()[source]

Update file path list with paths specified on initialization.

Uses paths from RstcheckMainRunner.check_paths, resolves all file paths and saves them in RstcheckMainRunner.files_to_check.

If a given path does not exist, it is filtered out and saved in RstcheckMainRunner.files_to_check.

Clear the current file list. Then get the file and directory paths specified with self.check_paths attribute set on initialization and search them for rst files to check. Add those files to the file list.

Return type:

None

check()[source]

Check all files in the file list and save the errors.

Multiple files are run in parallel.

A new call overwrite the old cached errors.

Return type:

None

print_result(output_file=None)[source]

Print all cached error messages and return exit code.

Parameters:

output_file (Optional[TextIO]) – file to print to; defaults to sys.stderr (if None)

Return type:

int

Returns:

exit code 0 if no error is printed; 1 if any error is printed

run()[source]

Run checks, print error messages and return the result.

Return type:

int

Returns:

exit code 0 if no error is printed; 1 if any error is printed

rstcheck_core.types module

rstcheck_core.types.SourceFileOrString

Path to source file or if it is a string then ‘<string>’ or ‘<stdin>’.

alias of Union[Path, Literal[‘<string>’], Literal[‘<stdin>’]]

class rstcheck_core.types.LintError(*args, **kwargs)[source]

Bases: dict

Dict with information about an linting error.

source_origin: Union[Path, Literal['<string>'], Literal['<stdin>']]
line_number: int
message: str
rstcheck_core.types.YieldedLintError

Yielded version of type LintError.

alias of Generator[LintError, None, None]

class rstcheck_core.types.IgnoreDict(*args, **kwargs)[source]

Bases: dict

Dict with ignore information.

messages: Optional[Pattern]
languages: List[str]
directives: List[str]
roles: List[str]
substitutions: List[str]
rstcheck_core.types.construct_ignore_dict(messages=None, languages=None, directives=None, roles=None, substitutions=None)[source]

Create an IgnoreDict with passed values or defaults.

Parameters:
Return type:

IgnoreDict

Returns:

IgnoreDict with passed values or defaults

rstcheck_core.types.CheckerRunFunction

Function to run checks.

Returned by rstcheck_core.checker.CodeBlockChecker.create_checker().

alias of Callable[[…], Generator[LintError, None, None]]

class rstcheck_core.types.InlineConfig(*args, **kwargs)[source]

Bases: dict

Dict with a config key and config value comming from a inline config comment.

key: str
value: str
class rstcheck_core.types.InlineFlowControl(*args, **kwargs)[source]

Bases: dict

Dict with a flow control value and line number comming from a inline config comment.

value: str
line_number: int