rstcheck_core package

Submodules

rstcheck_core.checker module

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

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)

Check the given rst source for issues.

Parameters:

• source_file (Path | Literal['<string>', '<stdin>'] | None) – Path to file the source comes from if it comes from a file; defaults to None

• ignores (IgnoreDict | None) – Ignore information; defaults to None

• report_level (ReportLevel) – Report level; defaults to rstcheck_core.config.DEFAULT_REPORT_LEVEL

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

• source (str)

Returns:

None

Yield:

Found issues

Return type:

Generator[LintError, None, None]

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

Bases: object

Checker for code blocks with different languages.

Initialize CodeBlockChecker.

Parameters:

• source_origin (Path | Literal['<string>', '<stdin>']) – Path to file the source comes from

• ignores (IgnoreDict | None) – Ignore information; defaults to None

• report_level (ReportLevel) – Report level; defaults to rstcheck_core.config.DEFAULT_REPORT_LEVEL

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

language_is_supported(language)

Check if given language can be checked.

Parameters:

language (str) – Language to check

Return type:

bool

Returns:

If language can be checked

create_checker(source_code, language)

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)

Call the appropriate checker function for the given language to check given source.

Parameters:

• source – Source code to check

• language (str) – Language of the source code

• source_code (str)

Returns:

None if language is not supported

Yield:

Found issues

Return type:

Generator[LintError, None, None]

check_python(source_code)

Check python source for syntax errors.

Parameters:

• source – Python source code to check

• source_code (str)

Returns:

None

Yield:

Found issues

Return type:

Generator[LintError, None, None]

check_json(source_code)

Check JSON source for syntax errors.

Parameters:

• source – JSON source code to check

• source_code (str)

Returns:

None

Yield:

Found issues

Return type:

Generator[LintError, None, None]

check_yaml(source_code)

Check YAML source for syntax errors.

Parameters:

• source – JSON source code to check

• source_code (str)

Returns:

None

Yield:

Found issues

Return type:

Generator[LintError, None, None]

check_xml(source_code)

Check XML source for syntax errors.

Parameters:

• source – XML source code to check

• source_code (str)

Returns:

None

Yield:

Found issues

Return type:

Generator[LintError, None, None]

check_rst(source_code)

Check nested rst source for syntax errors.

Parameters:

• source – rst source code to check

• source_code (str)

Returns:

None

Yield:

Found issues

Return type:

Generator[LintError, None, None]

check_doctest(source_code)

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)

Returns:

None

Yield:

Found issues

Return type:

Generator[LintError, None, None]

check_bash(source_code)

Check bash source for syntax errors.

Parameters:

• source – bash source code to check

• source_code (str)

Returns:

None

Yield:

Found issues

Return type:

Generator[LintError, None, None]

check_c(source_code)

Check C source for syntax errors.

Parameters:

• source – C source code to check

• source_code (str)

Returns:

None

Yield:

Found issues

Return type:

Generator[LintError, None, None]

check_cpp(source_code)

Check C++ source for syntax errors.

Parameters:

• source – C++ source code to check

• source_code (str)

Returns:

None

Yield:

Found issues

Return type:

Generator[LintError, None, None]

rstcheck_core.config module

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

Supported default config files.

class rstcheck_core.config.ReportLevel(*values)

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)

Bases: BaseModel

Rstcheck config file.

Raises:

• ValueError – If setting has incorrect value or type

• pydantic.ValidationError – If setting is not parsable into correct type

Parameters:

• report_level (ReportLevel | None)

• ignore_directives (list[str] | None)

• ignore_roles (list[str] | None)

• ignore_substitutions (list[str] | None)

• ignore_languages (list[str] | None)

• ignore_messages (Pattern[str] | None)

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

report_level: ReportLevel | None

ignore_directives: list[str] | None

ignore_roles: list[str] | None

ignore_substitutions: list[str] | None

ignore_languages: list[str] | None

ignore_messages: Pattern[str] | None

classmethod valid_report_level(value)

Validate the report_level setting.

Parameters:

value (Any) – Value to validate

Raises:

ValueError – If value is not a valid docutils report level

Return type:

ReportLevel | None

Returns:

Instance of ReportLevel or None if empty string.

classmethod split_str(value)

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:

list[str] | None

Returns:

List of things to ignore in the respective category

classmethod join_regex_str(value)

Validate and concatenate the ignore_messages setting to a RegEx string.

If a list is 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:

str | Pattern[str] | None

Returns:

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

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class rstcheck_core.config.RstcheckConfig(**data)

Bases: RstcheckConfigFile

Rstcheck config.

Raises:

• ValueError – If setting has incorrect value or type

• pydantic.ValidationError – If setting is not parsable into correct type

Parameters:

• report_level (ReportLevel | None)

• ignore_directives (list[str] | None)

• ignore_roles (list[str] | None)

• ignore_substitutions (list[str] | None)

• ignore_languages (list[str] | None)

• ignore_messages (Pattern[str] | None)

• config_path (Path | None)

• recursive (bool | None)

• warn_unknown_settings (bool | None)

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

config_path: Path | None

recursive: bool | None

warn_unknown_settings: bool | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

rstcheck_core.config.load_config_file(file_path, *, log_missing_section_as_warning=True, warn_unknown_settings=False)

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:

RstcheckConfigFile | None

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)

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:

RstcheckConfigFile | None

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)

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:

RstcheckConfigFile | None

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)

Analyze 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 directory; 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:

RstcheckConfigFile | None

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)

Merge two configs into a new one.

Parameters:

• config_base (RstcheckConfig) – The base config to merge into

• config_add (RstcheckConfig | RstcheckConfigFile) – The config that is merged into the config_base

• config_add_is_dominant (bool) – If the config_add overwrites values of config_base; defaults to True

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)

Get rstcheck inline configs from source.

Unknown configs are ignored.

Parameters:

• source (str) – Source to get config from

• source_origin (Path | Literal['<string>', '<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)

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 (Path | Literal['<string>', '<stdin>']) – Origin of the source with the inline ignore comments

• warn_unknown_settings (bool)

Returns:

None

Yield:

Found directives to ignore

Return type:

Generator[str, None, None]

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

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 (Path | Literal['<string>', '<stdin>']) – Origin of the source with the inline ignore comments

• warn_unknown_settings (bool)

Returns:

None

Yield:

Found roles to ignore

Return type:

Generator[str, None, None]

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

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 (Path | Literal['<string>', '<stdin>']) – Origin of the source with the inline ignore comments

• warn_unknown_settings (bool)

Returns:

None

Yield:

Found substitutions to ignore

Return type:

Generator[str, None, None]

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

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 (Path | Literal['<string>', '<stdin>']) – Origin of the source with the inline ignore comments

• warn_unknown_settings (bool)

Returns:

None

Yield:

Found languages to ignore

Return type:

Generator[str, None, None]

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

Get rstcheck inline flow control from source.

Unknown flow controls are ignored.

Parameters:

• source (str) – Source to get config from

• source_origin (Path | Literal['<string>', '<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)

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

Parameters:

• source (str) – Source to get config from

• source_origin (Path | Literal['<string>', '<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

Returns:

None

Yield:

Single values for the target_config

Return type:

Generator[int, None, None]

rstcheck_core.runner module

class rstcheck_core.runner.RstcheckMainRunner(check_paths, rstcheck_config, *, overwrite_config=True)

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)

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()

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()

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)

Print all cached error messages and return exit code.

Parameters:

output_file (TextIO | None) – 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()

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 = pathlib.Path | typing.Literal['<string>', '<stdin>']

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

class rstcheck_core.types.LintError

Bases: TypedDict

Dict with information about an linting error.

source_origin: Path | Literal['<string>', '<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

Bases: TypedDict

Dict with ignore information.

messages: Pattern[str] | None

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)

Create an IgnoreDict with passed values or defaults.

Parameters:

• messages (Pattern[str] | None) – Value for IgnoreDict.messages; None results in an empty list; defaults to None

• directives (list[str] | None) – Value for IgnoreDict.directives; None results in an empty list; defaults to None

• roles (list[str] | None) – Value for IgnoreDict.roles; None results in an empty list; defaults to None

• substitutions (list[str] | None) – Value for IgnoreDict.substitutions; None results in an empty list; defaults to None

• languages (list[str] | None)

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

Bases: TypedDict

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

key: str

value: str

class rstcheck_core.types.InlineFlowControl

Bases: TypedDict

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

value: str

line_number: int