Package API

pymdtools exposes a small package-level API with lazy imports. Importing the package itself stays lightweight; heavier integrations such as PDF conversion are only imported when the corresponding public symbol is accessed.

Public Shortcuts

  • convert_for_stdout: normalize text for console output.

  • markdown_file_beautifier: normalize a Markdown file in place.

  • convert_md_to_pdf: convert Markdown to PDF through the HTML/PDF pipeline.

  • search_include_refs_to_md_file: resolve Markdown include references.

Public API

pymdtools

Utilities for manipulating Markdown files and transforming them into other representations (HTML, PDF, etc.). The package focuses on practical Markdown workflows such as normalization/beautification and include-resolution.

This package-level module is designed to be production-hardened:

  • Light imports: importing pymdtools must not pull heavy dependencies.

  • Stable public surface: only symbols listed in __all__ are public.

  • Lazy loading: public callables are imported on-demand to reduce import time and to keep optional dependencies optional.

  • Actionable errors: missing submodules / optional dependencies raise informative ImportError.

Public API

The following functions are exposed at package level:

Notes

Lazy loading relies on PEP 562 (module-level __getattr__ / __dir__), thus Python >= 3.7 is required.

After the first access, lazily-loaded symbols are cached into the module namespace (globals()) for subsequent direct access.

Examples

Import the package (recommended):

>>> import pymdtools
>>> text = pymdtools.convert_for_stdout("# Title\n\nBody")
>>> pymdtools.markdown_file_beautifier("README.md")

Import a specific symbol directly:

>>> from pymdtools import convert_for_stdout
>>> convert_for_stdout("# Title")
pymdtools.convert_for_stdout(text: str, *, stream: ~typing.TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, fallback_encoding: str = 'utf-8', errors: str = 'replace') → str

Adapt a Unicode string to the encoding of the given text stream.

Parameters:

  • text (str) – Input Unicode string.

  • stream (TextIO, default=sys.stdout) – Target output stream. Its .encoding attribute is used when available.

  • fallback_encoding (str, default="utf-8") – Encoding used if the stream has no encoding.

  • errors (str, default="replace") – Error handler used for the encode/decode round-trip.

Returns:

Text safe to print to the given stream.

Return type:

str

pymdtools.convert_md_to_pdf(filename: str | PathLike[str] | Path, filename_ext: str = '.md', **kwargs: Any) → Path

Convert a Markdown file to PDF.

The conversion is performed in a temporary folder, then the generated PDF is copied next to the source Markdown file and post-processed with pdf_features().

Parameters:

  • filename – Markdown file to convert.

  • filename_ext – Expected Markdown extension.

  • **kwargs – Options forwarded to pdf_features().

Returns:

Generated PDF path.

pymdtools.markdown_file_beautifier(filename: str | PathLike[str] | Path, backup_option: bool = True, filename_ext: str = '.md', *, backup_ext: str = '.bak', read_encoding: str | None = None, write_encoding: str = 'utf-8') → str

Normalize a Markdown file in place.

The file is validated, read, optionally backed up, normalized with md_beautifier(), and written back with the requested encoding.

Backups are created before writing and use pymdtools.common.create_backup(). The file is written through pymdtools.common.set_file_content(), so the write path follows the common module’s atomic-write behavior.

Parameters:

  • filename – Markdown file to normalize.

  • backup_option – Whether to create a backup before overwriting the file.

  • filename_ext – Expected Markdown extension, including the leading dot.

  • backup_ext – Backup extension used when backup_option is true.

  • read_encoding – Encoding used to read the file. None triggers automatic detection in pymdtools.common.

  • write_encoding – Encoding used to write the normalized file.

Returns:

Normalized absolute filename as a string.

Raises:

  • FileNotFoundError – If filename does not exist.

  • IsADirectoryError – If filename is not a regular file.

  • ValueError – If the file extension is unexpected or the file is empty.

  • OSError – Propagated from filesystem helpers.

pymdtools.search_include_refs_to_md_file(filename: str | PathLike[str] | Path, *, backup_option: bool = True, backup_ext: str = '.bak', filename_ext: str = '.md', depth_up: int = 1, depth_down: int = -1) → str

Discover refs around a markdown file and apply include substitutions in-place.

This is a convenience function:

  1. Collect refs by scanning folders around filename (see get_refs_around_md_file)

  2. Apply includes into filename (see include_refs_to_md_file)

Parameters:

  • filename – Markdown file to process.

  • backup_option – Whether to create a backup before overwriting.

  • backup_ext – Backup extension (e.g. “.bak”).

  • filename_ext – Expected extension for filename.

  • depth_up – Number of parent directory levels to move up for the search root (>= 0).

  • depth_down – Depth for scanning downward (-1 unlimited, 0 current dir only, >0 limited).

Returns:

Normalized filename (string).

Raises:

  • ValueError – If depth_up < 0 or depth_down < -1.

  • KeyError/ValueError – Propagated from include resolution if refs are missing/malformed.

  • RuntimeError/Exception – Propagated from filesystem helpers.