Skip to content

API Reference

includepy

A Markdown extension that inserts code for Python objects (such as functions and classes).

Classes:

  • ProcessorState –

    Define an interface for processing Markdown lines.

  • EchoLines –

    Preserve existing Markdown content.

  • ParseBlock –

    Parse an IncludePy block and add the specified Python code to the output.

  • IncludePyError –

    Raised when an error is encountered while attempting to insert the code

  • IncludePyProc –

    The IncludePy preprocessor.

  • IncludePy –

    The IncludePy extension class.

Functions:

  • valid_options –

    Returns the valid option names.

  • default_options –

    Returns default values for options that have defaults.

  • string_to_bool –

    Convert a string option into a Boolean value.

  • find_object –

    Find a named object (e.g., function or class) in a syntax tree.

  • find_docstring –

    Find a docstring node in an object's syntax tree.

  • selected_lines –

    Return only selected lines from a code block.

  • makeExtension –

    Return an instance of the IncludePy extension.

includepy.ProcessorState

Define an interface for processing Markdown lines.

Methods:

  • read_line –

    Process an input line and return the updated processor state.

read_line 

read_line(input_line: str | None, output_lines: list[str]) -> ProcessorState

Process an input line and return the updated processor state.

Parameters:

  • input_line (str | None) –

    A line of text, or None to indicate the end of the file.

  • output_lines (list[str]) –

    The output Markdown lines, can be mutably updated.

Returns:

includepy.EchoLines

Bases: ProcessorState

Preserve existing Markdown content.

includepy.ParseBlock

Bases: ProcessorState

Parse an IncludePy block and add the specified Python code to the output.

includepy.IncludePyError

Bases: Exception

Raised when an error is encountered while attempting to insert the code for a Python object.

includepy.IncludePyProc

Bases: Preprocessor

The IncludePy preprocessor.

Methods:

  • run –

    Process the input Markdown content and include Python source code as

run 

run(lines: list[str]) -> list[str]

Process the input Markdown content and include Python source code as directed.

Parameters:

  • lines (list[str]) –

    A list of text lines.

Returns:

  • list[str] –

    The processed lines of text, with Python source code lines added as directed.

includepy.IncludePy

Bases: Extension

The IncludePy extension class.

Methods:

  • extendMarkdown –

    Register this extension with a Markdown processor.

extendMarkdown 

extendMarkdown(md: Markdown) -> None

Register this extension with a Markdown processor.

Parameters:

  • md (Markdown) –

    A Markdown processor.

Returns:

  • None –

includepy.valid_options 

valid_options() -> set[str]

Returns the valid option names.

includepy.default_options 

default_options() -> dict[str, str]

Returns default values for options that have defaults.

includepy.string_to_bool 

string_to_bool(value: str) -> bool

Convert a string option into a Boolean value.

includepy.find_object 

find_object(name: str | None, node: AST) -> AST

Find a named object (e.g., function or class) in a syntax tree.

includepy.find_docstring 

find_docstring(obj: AST) -> Expr | None

Find a docstring node in an object's syntax tree.

includepy.selected_lines 

selected_lines(input_lines: list[str], only_lines: str) -> list[str]

Return only selected lines from a code block.

Parameters:

  • input_lines (list[str]) –

    The input lines of text.

  • only_lines (str) –

    A string that contains one or more line-range specifiers, separated by commas. Each specifier must have one of the following forms: n for the nth input line, n- for every line from the nth to the end, -n for every line from the start up to the nth, or n-p for every line from the nth up to the pth. Note that line numbering begins at 1.

Returns:

  • list[str] –

    The selected lines of text.

includepy.makeExtension 

makeExtension(**kwargs: dict[str, Any]) -> IncludePy

Return an instance of the IncludePy extension.