Skip to content

api Module#

This module provides a programmatic Python interface for interacting with the PyMarkdown application, bypassing the command line. Readers should be familiar with the PyMarkdown linter and its command-line interface, since the API wraps these existing tools.

The API expands based on user requests for new functionality. If you need API access to existing command-line functionality, please submit a feature request via our feature request process.

API Action Methods#

PyMarkdownApi provides five primary API action methods and two version properties as its core functionality. Together, these APIs form the core of most common workflows in applying PyMarkdown to a set of Markdown files.

The primary questions users typically ask when applying the API are:

  • What Markdown files can I scan?
  • Are there any rule failures in those Markdown files?
  • Can I automatically fix any of those rule failures?

These questions form the basis for the primary workflow described below.

Although other workflows exist, this primary sequence covers the most common use cases for Markdown documents. This discovery -> lint -> remediate workflow allows users to verify their Markdown files against their desired formatting standards.

We cover the primary API elements here. Configuration is handled by the API Modifier Methods described below.

The following workflow demonstrates the recommended usage of the API methods in sequence. Each method's docstring provides detailed examples for that specific step.

import sys
from pymarkdown.api import PyMarkdownApi, PyMarkdownApiArgumentException, PyMarkdownApiNoFilesFoundException

# 0. Establish foundation.
path_to_scan = "docs/"
recurse_if_directory = False
api = PyMarkdownApi(inherit_logging=False).log_to_file("scan.log")

# 1. Discover
try:
    list_result = (
        api.list_path(path_to_scan, recurse_if_directory=recurse_if_directory)
    )
except PyMarkdownApiNoFilesFoundException:
    print(f"No files found in path '{path_to_scan}'.")
    sys.exit(1)

print(f"Found {len(list_result.matching_files)} files to scan.")

# 2. Scan
try:
    scan_result = (
        api.scan_path(path_to_scan, recurse_if_directory=recurse_if_directory)
    )
except PyMarkdownApiException as e:
    print(f"Scan failed: {e}")
    sys.exit(5)

if not scan_result.scan_failures and not scan_result.pragma_errors and not scan_result.critical_errors:
    print("All clear!")
    sys.exit(0)

print(f"Found {len(scan_result.scan_failures)} Rule Failures.")
print(f"Found {len(scan_result.pragma_errors)} Pragma Errors.")
print(f"Found {len(scan_result.critical_errors)} Critical Failures.")
if scan_result.critical_errors:
    sys.exit(5)

# 3. Fix
if not scan_result.scan_failures:
    sys.exit(0)

try:
    fix_result = (
        api.fix_path(path_to_scan, recurse_if_directory=recurse_if_directory)
    )
    if fix_result.critical_errors:
        print(f"Found {len(scan_result.critical_errors)} Critical Failures.")
        sys.exit(5)
    if fix_result.files_fixed:
        print(f"Fixed {len(fix_result.files_fixed)} files.")
        sys.exit(3)
    sys.exit(4)
except PyMarkdownApiException as e:
    print(f"Fix failed: {e}")
    sys.exit(5)

pymarkdown.api.PyMarkdownApi #

Module to provide for an API to directly communicate with PyMarkdown instead of using a command line.

Parameters:

  • inherit_logging (bool, default: False ) –

    If True, inherit the logging settings from the calling application. If False, will use the log_* functions to specify the logging properties.

Attributes: __inherit_logging (bool): Kept version of the inherit_logging parameter.

list_path(path_to_scan, recurse_if_directory=False, alternate_extensions=None, exclude_patterns=None, respect_gitignore=False) #

Scans a provided path for eligible Markdown files without scanning or modifying them.

This is the API interface equivalent for the pymarkdown scan --list-files command line action.

This method is usually the first step in the End-to-End Workflow, used to determine the files that will be processed later using the scan_path and fix_path methods.

See the End-to-End Workflow in the class documentation for the recommended pattern of using this method to prepare for scanning.

The filtering process for determining which files to scan (covered more thoroughly detailed in the Path section of the User's Guide) follows these steps:

  1. Discovery: path_to_scan and recurse_if_directory determine the initial set of files to be examined for eligibility.
  2. Eligibility: Files are filtered by extension (default .md), optionally overridden by alternate_extensions.
  3. Exclusion: exclude_patterns and respect_gitignore further narrow the file list.

Parameters:

  • path_to_scan (str) –

    The path to scan. Can be a file, a directory, or a glob pattern. If a relative path is provided, it is resolved against the current working directory.

  • recurse_if_directory (bool, default: False ) –

    If path_to_scan is a directory, setting this to True includes all subdirectories in the scan.

  • alternate_extensions (Optional[str], default: None ) –

    An optional comma-separated list of file extensions to scan. If not None and not an empty string, this list replaces the default .md extension entirely. Defaults to .md if None or an empty string is passed.

  • exclude_patterns (Optional[List[str]], default: None ) –

    If provided, glob patterns to exclude files or directories. Patterns are resolved relative to the current working directory, not the path_to_scan parameter. Exclusions are determined by the union of patterns in exclude_patterns and .gitignore files (if respect_gitignore is True). If a file matches any pattern in either list, it is excluded from the scan.

  • respect_gitignore (bool, default: False ) –

    If True, respect any .gitignore files found when scanning according to standard Git rules.

Returns:

Raises:

  • PyMarkdownApiArgumentException –

    If path_to_scan is empty or if alternate_extensions does not contain a valid list of file extensions. Valid file extensions start with a single period character and are followed by one or more ASCII alphanumeric characters.

  • PyMarkdownApiNoFilesFoundException –

    If no eligible files were found.

  • PyMarkdownApiException –

    Raised for unexpected internal errors, such as invalid configuration files, plugin loading failures, or unhandled I/O errors.

Examples:

Recommended Workflow: Discovering Files.#

The following example is the first part of the workflow demonstrated in the PyMarkdownApi examples. It prepares the file list for scan_path.

# SNIPPET: Part 1 of the End-to-End Workflow
# Assumes: api = PyMarkdownApi()
# Assumes: path = "docs/"
# Assumes: recurse = False

try:
    list_result = api.list_path(path, recurse_if_directory=recurse)
except PyMarkdownApiNoFilesFoundException:
    print("No files found.")
    return

if list_result.matching_files:
    print(f"Discovered {len(list_result.matching_files)} files.")

scan_path(path_to_scan, recurse_if_directory=False, alternate_extensions=None, exclude_patterns=None, respect_gitignore=False) #

Scan a provided path for eligible Markdown files and check them for rule violations and pragma errors.

This is the API interface equivalent for the pymarkdown scan command line action.

This method is the second step in the recommended End-to-End Workflow. See list_path for how to determine eligible files.

See the End-to-End Workflow in the class documentation for the recommended pattern of using this method to scan for rule failures.

Parameters:

  • path_to_scan (str) –

    The path to scan. Can be a file, a directory, or a glob pattern. If a relative path is provided, it is resolved against the current working directory.

  • recurse_if_directory (bool, default: False ) –

    If path_to_scan is a directory, setting this to True includes all subdirectories in the scan.

  • alternate_extensions (Optional[str], default: None ) –

    An optional comma-separated list of file extensions to scan. If not None and not an empty string, this list replaces the default .md extension entirely. Defaults to .md if None or an empty string is passed.

  • exclude_patterns (Optional[List[str]], default: None ) –

    If provided, glob patterns to exclude files or directories. Patterns are resolved relative to the current working directory, not the path_to_scan parameter. Exclusions are determined by the union of patterns in exclude_patterns and .gitignore files (if respect_gitignore is True). If a file matches any pattern in either list, it is excluded from the scan.

  • respect_gitignore (bool, default: False ) –

    If True, respect any .gitignore files found when scanning according to standard Git rules.

Returns:

  • PyMarkdownScanPathResult –

    A PyMarkdownScanPathResult object if the scan completes without raising an exception.

    • scan_failures: A list of PyMarkdownScanFailure objects. This list is empty if no rule violations were found. Each object in the list is a rule failure found in an eligible file.
    • pragma_errors: A list of PyMarkdownPragmaError objects. This list is empty if no pragma issues were found. Each object in the list is a failure to parse a Pragma command embedded within an eligible file.
    • critical_errors: Present only if enable_continue_on_error is enabled. If disabled, critical errors result in an exception being raised, and this list is never populated in the returned object.

Raises:

  • PyMarkdownApiArgumentException –

    If path_to_scan is empty or if alternate_extensions does not contain a valid list of file extensions. Valid file extensions start with a single period character and are followed by one or more ASCII alphanumeric characters.

  • PyMarkdownApiNoFilesFoundException –

    If no eligible files were found.

  • PyMarkdownApiException –

    Raised for unexpected internal errors, such as invalid configuration files, plugin loading failures, or unhandled I/O errors. Note on enable_continue_on_error: If this option is enabled, certain System Errors are not raised as exceptions. Instead, they are collected in the critical_errors list of the returned PyMarkdownScanPathResult object.

Examples:

Recommended Workflow: Scanning for Violations.#

This example demonstrates the core scanning step of the recommended workflow. It assumes you have already discovered your files using list_path with the same path arguments. This ensures that the configuration and file targeting are consistent.

# SNIPPET: Part 2 of the End-to-End Workflow
# Assumes: api and path are defined from the previous step.

try:
    # IMPORTANT: Use the EXACT same path and recurse arguments as list_path
    scan_result = api.scan_path(path, recurse_if_directory=recurse)
except PyMarkdownApiException as e:
    print(f"Scan failed: {e}")
    return

if scan_result.scan_failures:
    print(f"Found {len(scan_result.scan_failures)} issues.")

fix_path(path_to_scan, recurse_if_directory=False, alternate_extensions=None, exclude_patterns=None, respect_gitignore=False) #

Scans a provided path for eligible Markdown files and applies automatic fixes for any rule violations that have auto-fix capabilities.

This is the API interface equivalent for the pymarkdown fix command line action.

This method is typically the final step in the End-to-End Workflow, applied after identifying issues via scan_path.

See the End-to-End Workflow in the class documentation for the recommended pattern of using this method to fix any rule violations for plugin rules that support the auto-fix capability.

Note: This method permanently modifies the source files in place. Automatic fixing will only be applied for rule plugins supporting the auto-fix capability.

Parameters:

  • path_to_scan (str) –

    The path to scan. Can be a file, a directory, or a glob pattern. If a relative path is provided, it is resolved against the current working directory.

  • recurse_if_directory (bool, default: False ) –

    If path_to_scan is a directory, setting this to True includes all subdirectories in the scan.

  • alternate_extensions (Optional[str], default: None ) –

    An optional comma-separated list of file extensions to scan. If not None and not an empty string, this list replaces the default .md extension entirely. Defaults to .md if None or an empty string is passed.

  • exclude_patterns (Optional[List[str]], default: None ) –

    If provided, glob patterns to exclude files or directories. Patterns are resolved relative to the current working directory, not the path_to_scan parameter. Exclusions are determined by the union of patterns in exclude_patterns and .gitignore files (if respect_gitignore is True). If a file matches any pattern in either list, it is excluded from the scan.

  • respect_gitignore (bool, default: False ) –

    If True, respect any .gitignore files found when scanning according to standard Git rules.

Returns:

  • PyMarkdownFixResult –

    A PyMarkdownFixResult object containing only the files that were successfully modified and written to disk, along with any critical errors encountered.

    • files_fixed: A list of strings containing the paths of files that were modified and written to disk. Files that were scanned but had no auto-fixable issues, or where all violations were non-auto-fixable, are not included in this list.
    • critical_errors: Present only if enable_continue_on_error is enabled. If disabled, critical errors result in an exception being raised, and this list is never populated in the returned object.

Raises:

  • PyMarkdownApiArgumentException –

    If path_to_scan is empty or if alternate_extensions does not contain a valid list of file extensions. Valid file extensions start with a single period character and are followed by one or more ASCII alphanumeric characters.

  • PyMarkdownApiNoFilesFoundException –

    If no eligible files were found.

  • PyMarkdownApiException –

    Raised for unexpected internal errors, such as invalid configuration files, plugin loading failures, or unhandled I/O errors. Note on enable_continue_on_error: If this option is enabled, certain System Errors are not raised as exceptions. Instead, they are collected in the critical_errors list of the returned PyMarkdownFixResult object.

Examples:

Recommended Workflow: Fixing Issues.#

This example demonstrates the final step in the recommended workflow: applying automatic fixes. It assumes you have already discovered files with list_path and scanned them with scan_path (see those docstrings for earlier steps). This ensures that the configuration and file targeting are consistent between the scan and fix operations.

# SNIPPET: Part 3 of the End-to-End Workflow
# Assumes: api and path are defined from the previous steps.

try:
    # IMPORTANT: Use the EXACT same path and recurse arguments as list_path/scan_path
    fix_result = api.fix_path(path, recurse_if_directory=recurse)
except PyMarkdownApiException as e:
    print(f"Fix failed: {e}")
    return

if fix_result.files_fixed:
    print(f"Fixed: {fix_result.files_fixed}")

scan_string(string_to_scan) #

Scan a provided Markdown string for rule violations and pragma errors.

This is the API interface equivalent for scanning a Markdown document provided via standard input (stdin), similar to the pymarkdown scan-stdin command line action.

This method is the alternative to scan_path for cases where the Markdown content is available as a string rather than a file on disk. It is typically used if the actual scanning content is provided dynamically or simply as a standalone check for generated Markdown strings.

Parameters:

  • string_to_scan (str) –

    The Markdown string to scan. This string is interpreted directly as the content of a Markdown document.

Returns:

  • PyMarkdownScanPathResult –

    A PyMarkdownScanPathResult object if the scan completes without raising an exception.

    • scan_failures: A list of PyMarkdownScanFailure objects. This list is empty if no rule violations were found. Each object in the list is a rule failure found in the provided string.
    • pragma_errors: A list of PyMarkdownPragmaError objects. This list is empty if no pragma issues were found. Each object in the list is a failure to parse a Pragma command embedded within the provided string.
    • critical_errors: Present only if enable_continue_on_error is enabled. If disabled, critical errors result in an exception being raised, and this list is never populated in the returned object.

Raises:

  • PyMarkdownApiArgumentException –

    If string_to_scan is empty.

  • PyMarkdownApiException –

    Raised for unexpected internal errors, such as invalid configuration files, plugin loading failures, or unhandled processing errors. Note on enable_continue_on_error: If this option is enabled, certain System Errors are not raised as exceptions. Instead, they are collected in the critical_errors list of the returned PyMarkdownScanPathResult object.

Examples:

Scanning a String for Violations.#

This example demonstrates scanning a Markdown string directly without needing a file path.

from pymarkdown.api import PyMarkdownApi, PyMarkdownApiException

markdown_content = """# Header

This is a paragraph with some text.
"""

try:
    scan_result = api.scan_string(markdown_content)
except PyMarkdownApiException as e:
    print(f"Scan failed: {e}")
    return

if scan_result.scan_failures:
    print(f"Found {len(scan_result.scan_failures)} issues.")
else:
    print("All clear!")

fix_string(string_to_scan) #

Scan a provided Markdown string and apply any eligible automatic fixes.

This is the API interface equivalent of:

  • writing the provided string_to_scan contents to a temporary file
  • applying a the pymarkdown fix command line to the temporary file
  • reading the fixed contents of the temporary file into the fixed_file attribute of the PyMarkdownFixStringResult object

This method is the alternative to fix_path for cases where the Markdown content is available as a string rather than a file on disk. It allows for programmatic fixing of generated or dynamically created Markdown content.

Note: This method does not modify the original string argument passed in. Instead, it returns a result object containing the fixed string content in memory.

Parameters:

  • string_to_scan (str) –

    The Markdown string to scan and fix. This string is interpreted directly as the content of a Markdown document.

Returns:

  • PyMarkdownFixStringResult –

    A PyMarkdownFixStringResult object containing:

    • was_fixed: A boolean indicating whether any fixes were applied to the document.
    • fixed_file: The Markdown string content with any eligible fixes applied. If no fixes were applied, this is identical to the input string_to_scan.

Raises:

Examples:

Fixing a String.#

This example demonstrates fixing a Markdown string directly.

from pymarkdown.api import PyMarkdownApi, PyMarkdownApiException

markdown_content = """# Header

Paragraph with some text.
"""

try:
    fix_result = api.fix_string(markdown_content)
except PyMarkdownApiException as e:
    print(f"Fix failed: {e}")
    return

if fix_result.was_fixed:
    print("Fixes were applied.")
    print(fix_result.fixed_file)
else:
    print("No fixes needed.")

interface_version property #

Report on the interface version.

The history of the interface versions and what they support is as follows:

Version Description
1 Initial version.

Returns:

  • int –

    The current plugin interface version. The current plugin interface version is 1.

Examples:

This function queries the current version of this API.

from pymarkdown.api import PyMarkdownApi

print(f"PyMarkdown API version = {PyMarkdownApi().interface_version}")

application_version property #

Report on the application version.

This is the API interface equivalent for the pymarkdownlnt version command line action.

Returns:

  • str –

    The current application version.

Examples:

This function queries the current version of PyMarkdown.

from pymarkdown.api import PyMarkdownApi

print(f"PyMarkdown version = {PyMarkdownApi().application_version}")

API Modifier Methods#

Modifier methods apply configuration to the PyMarkdown API, altering how the API Action Methods process Markdown files. Each modifier in this section is modeled after a specific command line argument used to alter PyMarkdown's behavior. Furthermore, each modifier's documentation includes an explicit reference to that corresponding CLI argument. Because of this direct mapping, all modifiers support method chaining, allowing configurations to be applied in a fluent, sequential manner, analogous to specifying multiple command-line arguments.

For example, the following statement is a fluent example of how to use these modifiers in a function chain:

  fix_result = (
    PyMarkdownApi()
      .enable_stack_trace()
      .log_debug_and_above()
      .fix_string("something")
  )

The examples use scan_path primarily for consistency; however, modifiers are compatible with all action methods.

pymarkdown.api.PyMarkdownApi(inherit_logging=False) #

Module to provide for an API to directly communicate with PyMarkdown instead of using a command line.

Parameters:

  • inherit_logging (bool, default: False ) –

    If True, inherit the logging settings from the calling application. If False, will use the log_* functions to specify the logging properties.

Attributes: __inherit_logging (bool): Kept version of the inherit_logging parameter.

Initialize a new instance of the PyMarkdownApi class.

disable_rule_by_identifier(rule_identifier) #

Disables the rule specified by the provided identifier.

This is the API interface equivalent for the --disable-rules command line argument. In advanced scenarios, providing * as the rule_identifier will disable all rules as documented in the Selectively Enable Rule Plugins section.

Parameters:

  • rule_identifier (str) –

    The unique identifier of the rule to disable.

Raises:

Returns:

Examples:

This example disables a single rule by one of its identifiers.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .disable_rule_by_identifier("md031")
        .scan_path("file.md")
)

enable_rule_by_identifier(rule_identifier) #

Enables the rule specified by the provided identifier.

This is the API interface equivalent for the --enable-rules command line argument.

Parameters:

  • rule_identifier (str) –

    The unique identifier of the rule to enable.

Raises:

Returns:

Examples:

This example enables a single rule by one of its identifiers.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .enable_rule_by_identifier("md031")
        .scan_path("file.md")
)

enable_extension_by_identifier(extension_identifier) #

Enables the extension specified by the provided identifier.

This is the API interface equivalent for the --enable-extensions command line argument.

Parameters:

  • extension_identifier (str) –

    The unique identifier of the extension to enable.

Raises:

Returns:

Examples:

This example enables a single extension by its identifier.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .enable_extension_by_identifier("front-matter")
        .scan_path("file.md")
)

configuration_file_path(path_to_config_file) #

Specifies the configuration file path for this API instance.

This is the API interface equivalent for the --config command line argument.

Parameters:

  • path_to_config_file (str) –

    The file path to the configuration file to use.

Raises:

Returns:

Examples:

This example sets the path to the configuration file to use.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .configuration_file_path("pymarkdown.cfg")
        .scan_path("file.md")
)

set_boolean_property(property_name, property_value) #

Sets a named configuration property to a boolean value.

This is the API interface equivalent for the --set command line argument. The method automatically formats the value with the $! prefix, as per the configuration advanced Set Command documentation.

Parameters:

  • property_name (str) –

    The full hierarchical name of the property to set.

  • property_value (bool) –

    The boolean value to assign to the property.

Raises:

Returns:

Examples:

This example sets a boolean value for a specific configuration item.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .set_boolean_property("plugins.md007.enabled", True)
        .scan_path("file.md")
)

set_integer_property(property_name, property_value) #

Sets a named configuration property to an integer value.

This is the API interface equivalent for the --set command line argument. The method automatically formats the value with the $# prefix, as per the configuration advanced Set Command documentation.

Parameters:

  • property_name (str) –

    The full hierarchical name of the property to set.

  • property_value (int) –

    The integer value to assign to the property.

Raises:

Returns:

Examples:

This example sets an integer value for a specific configuration item.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .set_integer_property("plugins.md007.code_block_line_length", 160)
        .scan_path("file.md")
)

set_string_property(property_name, property_value) #

Sets a named configuration property to a string value.

This is the API interface equivalent for the --set command line argument.

Parameters:

  • property_name (str) –

    The full hierarchical name of the property to set.

  • property_value (str) –

    The string value to assign to the property.

Raises:

Returns:

Examples:

This example sets a string value for a specific configuration item.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .set_string_property("plugins.heading-style-h1.style", "consistent")
        .scan_path("file.md")
)

set_property(property_name, property_value) #

Sets a named configuration property to a value.

This is the API interface equivalent for the --set command line argument.

Note: If at all possible, the other three set_*_property methods should be used as they ensure that the correct type of value is set as the configuration item value. This method converts any value provided in property_value to its string representation before assigning it to the configuration item.

Parameters:

  • property_name (str) –

    The full hierarchical name of the property to set.

  • property_value (Any) –

    The value to assign to the property. It will be converted to a string.

Raises:

Returns:

Examples:

This example sets a configuration item's value to a string representation of the provided argument.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .set_property("plugins.heading-style-h1.style", 1)
        .scan_path("file.md")
)

enable_strict_configuration() #

Enables strict validation for all configuration properties, including those defined in configuration files and those set programmatically.

This is the API interface equivalent for the --strict-config command line argument.

Returns:

Examples:

This example enables strict adherence to configuration requirements.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .enable_strict_configuration()
        .scan_path("file.md")
)

log_debug_and_above() #

Sets PyMarkdown's logging level to DEBUG or higher.

This is the API interface equivalent for the --log-level command line argument with the accompanying argument set to DEBUG. This method is often used in conjunction with the log_to_file method to configure both the detail level and output destination.

Raises:

Returns:

Examples:

This example sets the logging level to DEBUG.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .log_debug_and_above()
        .log_to_file("pymarkdown.log")
        .scan_path("file.md")
)

log_info_and_above() #

Sets PyMarkdown's logging level to INFO or higher.

This is the API interface equivalent for the --log-level command line argument with the accompanying argument set to INFO. This method is often used in conjunction with the log_to_file method to configure both the detail level and output destination.

Raises:

Returns:

Examples:

This example sets the logging level to INFO.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .log_info_and_above()
        .log_to_file("pymarkdown.log")
        .scan_path("file.md")
)

log_warning_and_above() #

Sets PyMarkdown's logging level to WARNING or higher.

This is the API interface equivalent for the --log-level command line argument with the accompanying argument set to WARNING. This method is often used in conjunction with the log_to_file method to configure both the detail level and output destination.

Raises:

Returns:

Examples:

This example sets the logging level to WARNING.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .log_warning_and_above()
        .log_to_file("pymarkdown.log")
        .scan_path("file.md")
)

log_error_and_above() #

Sets PyMarkdown's logging level to ERROR or higher.

This is the API interface equivalent for the --log-level command line argument with the accompanying argument set to ERROR. This method is often used in conjunction with the log_to_file method to configure both the detail level and output destination.

Raises:

Returns:

Examples:

This example sets the logging level to ERROR.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .log_error_and_above()
        .log_to_file("pymarkdown.log")
        .scan_path("file.md")
)

log_critical_and_above() #

Sets PyMarkdown's logging level to CRITICAL or higher.

This is the API interface equivalent for the --log-level command line argument with the accompanying argument set to CRITICAL. This method is often used in conjunction with the log_to_file method to configure both the detail level and output destination.

Raises:

Returns:

Examples:

This example sets the logging level to CRITICAL.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .log_critical_and_above()
        .log_to_file("pymarkdown.log")
        .scan_path("file.md")
)

log(log_level) #

Sets the logging level using a string value.

This is the API interface equivalent for the --log-level command line argument. This method is often used in conjunction with the log_to_file method to configure both the detail level and output destination.

Parameters:

  • log_level (str) –

    One of "CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG".

Raises:

Returns:

Examples:

This example sets the logging level to INFO.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .log("INFO")
        .log_to_file("pymarkdown.log")
        .scan_path("file.md")
)

log_to_file(log_file_path) #

Specifies the file path to which log messages will be written.

This is the API interface equivalent for the --log-file command line argument. This method is typically used with one of the other log* modifiers to set the logging level to write to the file specified by this method.

Parameters:

  • log_file_path (str) –

    The file path where log messages will be written.

Raises:

Returns:

Examples:

This example directs logging messages to the specified file.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .log("INFO")
        .log_to_file("pymarkdown.log")
        .scan_path("file.md")
)

add_plugin_path(path_to_plugin) #

Adds a plugin path that points to a directory containing plugins or to a single plugin.

This is the API interface equivalent for the --add-plugin command line argument.

Parameters:

  • path_to_plugin (str) –

    The path to a plugin directory or a single plugin file.

Raises:

Returns:

Examples:

This example demonstrates how to add a plugin path for PyMarkdown to use.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .add_plugin_path("my_plugin.py")
        .scan_path("file.md")
)

enable_stack_trace() #

Enables the reporting of stack traces for any exceptions caught and reported by the API.

This is the API interface equivalent for the --stack-trace command line argument.

This provides additional details about the nature of any reported exception.

Returns:

Examples:

This example enables the reporting of stack traces in case of a raised exception.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .enable_stack_trace()
        .scan_path("file.md")
)

disable_json5_configuration() #

Disables the JSON5 parser for configuration files, falling back to the standard Python json module.

This is the API interface equivalent for the --no-json5 command line argument.

Returns:

Examples:

This example disables the use of the JSON5 parser for configuration files.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .disable_json5_configuration()
        .scan_path("file.md")
)

enable_continue_on_error() #

Enables continued scanning even if critical errors are encountered in some files.

This is the API interface equivalent for the --continue-on-error command line argument.

This method is primarily intended for debugging or reporting when critical errors occur during file processing. It is not intended for general error handling or regular use. When a critical error occurs, the exception is normally raised immediately. This modifier allows processing to continue by returning the exception details in the critical_errors field of the result object instead.

It is recommended to use this only when debugging critical errors for reporting purposes, not for production stability. It allows you to report the critical exception to the development team and how to reproduce it via our usual reporting process while the team investigates the issue and releases a code change.

Returns:

Examples:

This example allows scanning to continue even if critical errors occur, such as encountering a file that cannot be read. The errors are collected in the critical_errors attribute of the returned result object.

from pymarkdown.api import PyMarkdownApi

scan_result = (
    PyMarkdownApi()
        .enable_continue_on_error()
        .scan_path("file.md")
)

ApiPresentation() #

Bases: MainPresentation

Class to provide for the output of the PyMarkdown application.

Initialize a new instance of the __ApiPresentation class.

print_system_output(output_string) #

Root function to output to standard out.

print_system_error(error_string) #

Root function to output to standard error.

print_pragma_failure(scan_file, line_number, pragma_error) #

Print a failure to compile the pragma.

Scan Results#

pymarkdown.api.PyMarkdownScanPathResult dataclass #

This dataclass encapsulated the results from either the scan_path or scan_string methods.

The attributes provide details on rule failures, pragma parsing errors, and any critical errors encountered during the scan.

Examples:

This example shows outputting information on the number of each class of failure, along with details for each critical error reported. Note that examples showing the details for the Rule Failures and Pragma Errors are provided in the PyMarkdownScanFailure and PyMarkdownPragmaError examples.

from pymarkdown.api import PyMarkdownApi, PyMarkdownApiException

# 1. Setup the API and enable 'continue_on_error' to ensure critical_errors are
# populated instead of raising an exception immediately. This allows us to
# demonstrate all 3 attributes.
api = PyMarkdownApi().enable_continue_on_error()

# 2. Perform the scan
try:
    scan_result = (
        api.scan_path("docs/", recurse_if_directory=True)
    )
except PyMarkdownApiException as e:
    print(f"Scan failed with critical error: {e}")
    scan_result = None

if scan_result:
    # --- Attribute 1: scan_failures ---
    if scan_result.scan_failures:
        print(f"\nFound {len(scan_result.scan_failures)} rule failures(s):")
        # See the example for PyMarkdownScanFailure for more detailed output.
    else:
        print("\nNo rule failures found.")

    # --- Attribute 2: pragma_errors ---
    # These are errors in PyMarkdown pragma commands embedded in the files.
    if scan_result.pragma_errors:
        print(f"\nFound {len(scan_result.pragma_errors)} pragma error(s):")
        # See the example for PyMarkdownPragmaError for more detailed output.
    else:
        print("\nNo pragma errors found.")

    # --- Attribute 3: critical_errors ---
    # These are critical system errors (e.g., file not found, encoding issues)
    # that occurred during scanning, populated due to `enable_continue_on_error`.
    if scan_result.critical_errors:
        print(f"\nFound {len(scan_result.critical_errors)} critical error(s):")
        for error in scan_result.critical_errors:
            print(f"  - {error}")
        print("-" * 40)
    else:
        print("\nNo critical errors encountered.")

scan_failures instance-attribute #

A list of PyMarkdownScanFailure objects representing rule failures.

pragma_errors instance-attribute #

A list of PyMarkdownPragmaError objects representing pragma errors.

critical_errors instance-attribute #

A list of critical error messages encountered during the scan. Populated only if enable_continue_on_error is present as parameter in the calling method and if it is enabled. Empty if no critical errors occurred.

pymarkdown.api.PyMarkdownScanFailure dataclass #

A dataclass containing information about a rule failure from a rule plugin.

This is the API interface encapsulation of the Rule Failure Format, providing an instance of this class instead of outputting the information to standard output.

Each instance represents a single rule failure encountered in a Markdown file during the execution of the scan_path method or the scan_string method. The encapsulated fields provide the following details about the scan failure:

  • the location where the scan failure occurred
  • the specific location within that location that triggered the scan failure
  • the exact rule that was triggered

If applicable, extra information about why the rule triggered may be included in the extra_error_information field. This information is rule-dependent and is intended to provide extra clarity about the specific rule failure.

For more information consult the Rule Failure Format section of our User's Guide.

Examples:

This example shows outputting information on the number of rule failures, and for each rule failure found, the information from each attribute of the rule failure.

from pymarkdown.api import PyMarkdownApi

api = PyMarkdownApi()
scan_result = api.scan_path("docs/")

if scan_result.scan_failures:
    print(f"\nFound {len(scan_result.scan_failures)} rule failures(s):")
    for failure in scan_result.scan_failures:
        print(f"  - File: {failure.scan_file}")
        print(f"    Line: {failure.line_number}, Column: {failure.column_number}")
        print(f"    Rule: {failure.rule_id} ({failure.rule_name})")
        print(f"    Desc: {failure.rule_description}")
        if failure.extra_error_information:
            print(f"    Extra: {failure.extra_error_information}")
        print("-" * 40)
else:
    print("\nNo rule failures found.")

scan_file instance-attribute #

File that was being scanned when the failure occurred.

line_number instance-attribute #

Line number of the triggered rule failure.

column_number instance-attribute #

Column number of the triggered rule failure.

rule_id instance-attribute #

ID of the rule that triggered the rule failure.

rule_name instance-attribute #

The names of the rule that triggered the rule failure.

rule_description instance-attribute #

A detailed description of the rule that triggered the rule failure.

extra_error_information instance-attribute #

Optional string providing more information on why the rule was triggered.

pymarkdown.api.PyMarkdownPragmaError dataclass #

A dataclass containing details of a pragma parsing error.

This is the API interface encapsulation for Pragma Errors, returning an instance of this object rather than outputting the information to standard output.

Each instance of this class specifies a single Pragma Error encountered during the execution of the scan_path method or the scan_string method.

The encapsulated fields provide the following details about the pragma error:

  • the location where the pragma error occurred
  • the position within that location that triggered the pragma error
  • specific details about the error detected by PyMarkdown

Note: When dealing with the output from the scan_path method, the location is always a path to the file when the error occurred. When dealing with the output from the scan_string method, the location is always set to in-memory.

More information on Pragmas and their use is available here.

Examples:

This example shows outputting information on the number of Pragma Errors, and for each Pragma Error found, the information from each attribute of the Pragma Error.

from pymarkdown.api import PyMarkdownApi

api = PyMarkdownApi()
scan_result = api.scan_path("docs/")

if scan_result.pragma_errors:
    print(f"\nFound {len(scan_result.pragma_errors)} pragma error(s):")
    for error in scan_result.pragma_errors:
        print(f"  - File: {error.file_path}")
        print(f"    Line: {error.line_number}")
        print(f"    Error: {error.pragma_error}")
        print("-" * 40)
else:
    print("\nNo pragma errors found.")

file_path instance-attribute #

The path to the file containing the invalid pragma.

line_number instance-attribute #

The line number where the pragma is contained.

pragma_error instance-attribute #

The error message reported by PyMarkdown.

Fix Results#

pymarkdown.api.PyMarkdownFixResult dataclass #

Class containing the results from the fix_path method.

This is the API interface encapsulation for the result of executing the pymarkdown fix command.

The only information that PyMarkdown provides about the fixed documents is the names of the documents that were fixed. As such, this result simply provides the path names for any fixed Markdown files.

Examples:

This example shows outputting information on the number of files fixed and the number of critical errors reported.

from pymarkdown.api import PyMarkdownApi, PyMarkdownApiException

# 1. Setup the API and enable 'continue_on_error' to ensure critical_errors are
# populated instead of raising an exception immediately.
api = PyMarkdownApi().enable_continue_on_error()

# 2. Try and remediate any issues.
try:
    fix_result = (
        api.fix_path("docs/", recurse_if_directory=True)
    )
except PyMarkdownApiException as e:
    print(f"Fix failed with critical error: {e}")
    fix_result = None

if fix_result:
    # --- Attribute 1: files_fixed ---
    if fix_result.files_fixed:
        print(f"\nFixed {len(fix_result.files_fixed)} Markdown file(s):")
        for fixed_file in fix_result.files_fixed:
            print(f"  - {fixed_file}")
    else:
        print("\nNo Markdown files were fixed.")

    # --- Attribute 2: critical_errors ---
    # These are critical system errors (e.g., file not found, encoding issues)
    # that occurred during remediation, populated due to `enable_continue_on_error`.
    if fix_result.critical_errors:
        print(f"\nFound {len(fix_result.critical_errors)} critical error(s):")
        for error in fix_result.critical_errors:
            print(f"  - {error}")
        print("-" * 40)
    else:
        print("\nNo critical errors encountered.")

files_fixed instance-attribute #

A list of paths to the files that were successfully fixed.

critical_errors instance-attribute #

A list of critical error messages encountered during the scan. Populated only if enable_continue_on_error is present as parameter in the calling method and if it is enabled. Empty if no critical errors occurred.

pymarkdown.api.PyMarkdownFixStringResult dataclass #

Class to encapsulate the results for the fix_string method.

This is the API interface encapsulation for the result of executing the pymarkdown fix command against a temporarily file that contains a string that was passed to the fix_string method.

This result contains information about fixes applied to the input string, interpreted as a Markdown document.

Examples:

This example shows a Markdown string being passed into the fix_string method and fixes being applied to that string before it returns.

from pymarkdown.api import PyMarkdownApi

# 1. Initialize the API
api = PyMarkdownApi()

# 2. Define a Markdown string with potential issues
original_markdown = """My list
1. Item 1
 2. Item 2
3. Item 3
 4. Item 4
"""

# 3. Call fix_string
# Note: We enable specific rules to demonstrate "fixing" behavior.
# `md005`/`list-indent` will align all list items
try:
    fix_result = api.fix_string(original_markdown)
except Exception as e:
    print(f"An error occurred: {e}")
    fix_result = None

# 4. Inspect the result attributes
if fix_result:
    # --- Attribute 1: was_fixed ---
    # This boolean indicates if the returned 'fixed_file' is different from the input.
    if fix_result.was_fixed:
        print("The Markdown content was successfully fixed.")
    else:
        print("No fixes were necessary. The content is already clean.")

    # --- Attribute 2: fixed_file ---
    # This contains the corrected Markdown string.
    print("\n--- Fixed Content ---")
    print(fix_result.fixed_file)
    print("--- End of Fixed Content ---")

was_fixed instance-attribute #

Indicates whether the string content was modified by the fix operation.

fixed_file instance-attribute #

The fixed Markdown string, if any fixes were applied. Otherwise, identical to the input string.

List Results#

pymarkdown.api.PyMarkdownListPathResult dataclass #

Class to contain the results of the list_path function.

This object returns a list of files that PyMarkdown understands to be eligible for scanning, without having scanned those files.

Examples:

This example shows outputting information on the number of eligible files found.

from pymarkdown.api import PyMarkdownApi, PyMarkdownApiException

# 1. Initialize the API.
api = PyMarkdownApi()

# 2. Look for files along our stated path.
try:
    list_result = (
        api.list_path("docs/", recurse_if_directory=True)
    )
except PyMarkdownApiNoFilesFoundException as e:
    print("No matching files were found.")
    return

# 3. Print the information contained in list_result.
print(f"Number of matching files: {len(list_result.matching_files)}")
for file_path in list_result.matching_files:
    print(f"  - {file_path}")

matching_files instance-attribute #

List of filenames that match the specifications of the requested path.

Exceptions#

pymarkdown.api.PyMarkdownApiException #

Bases: Exception

Class to provide for an exception that is thrown by the API layer.

This base PyMarkdown application exception is explicitly thrown when a unexpected error occurs that is not categorized as one of the other application exceptions. Where possible, child classes of this class should be used to provide more specific information regarding the nature of the exception.

Attributes:

  • reason (str) –

    Reported reason why the action failed.

pymarkdown.api.PyMarkdownApiArgumentException #

Bases: PyMarkdownApiException

Class to provide for an argument that an exception is not valid.

This exception is raised when an argument to a function falls outside of the expected behavior for that function. This can mean that a str parameter is unexpectedly empty or that the parameter is not one of the allowed values for that parameter.

Attributes:

  • reason (str) –

    Reported reason why the action failed.

  • argument_name (str) –

    Name of the argument that caused this exception to be raised.

pymarkdown.api.PyMarkdownApiNoFilesFoundException #

Bases: PyMarkdownApiException

Class to provide for an exception that the invoked API was not able to find at least one file to process.

This is raised as an exception if at least one file to scan or fix is not encountered. As the PyMarkdown application is a scanning application, not finding a single Markdown document to scan is typically an exceptional case.

Attributes:

  • reason (str) –

    Reported reason why the action failed.

pymarkdown.api.PyMarkdownApiNotSupportedException #

Bases: PyMarkdownApiException

Class to provide for an exception that a given situation is not supported.

This exception is raised when the PyMarkdownApi instance is created with the inherit_logging parameter set to True, followed by a call to one of the functions that alters the logging behavior of the application.

Attributes:

  • reason (str) –

    Reported reason why the action failed.