Development tools API

Read contents of Markdown fenced code blocks

class phmdoctest.tool.FCBChooser(markdown_filename: str)

Select labeled fenced code block from the Markdown file.

FCBChooser.__init__(markdown_filename: str)

Gather labelled Markdown fenced code blocks in the file.

Parameters:markdown_filename – Path to the Markdown file
FCBChooser.contents(label: str = '') → str

Return contents of the labeled fenced code block with label.

Parameters:label – Value of label directive placed on the fenced code block in the Markdown file.
Returns:Contents of the labeled fenced code block as a string or empty string if the label is not found. Fenced code block strings typically end with a newline.
phmdoctest.tool.labeled_fenced_code_blocks(markdown_filename: str) → List[phmdoctest.tool.LabeledFCB]

Return Markdown fenced code blocks that have label directives.

Label directives are placed immediately before a fenced code block in the Markdown source file. The directive can be placed before any fenced code block. The label directive is the HTML comment <!--phmdoctest-label VALUE--> where VALUE is typically a legal Python identifier. The space must be present before VALUE. The label directive is also used to name the test function in generated code. When used that way, it must be a valid Python identifier. If there is more than one label directive on the block, the label value that occurs earliest in the file is used.

Parameters:markdown_filename – Path to the Markdown file.
Returns:List of LabeledFCB objects.

LabeledFCB is a NamedTuple with these fields:

  • label is the value of a label directive placed in a HTML comment before the fenced code block.
  • line is the line number in the Markdown file where the block starts.
  • contents is the fenced code block contents as a string.
phmdoctest.tool.fenced_code_blocks(markdown_filename: str) → List[str]

Return Markdown fenced code block contents as a list of strings.

Parameters:markdown_filename – Path to the Markdown file.
Returns:List of strings, one for the contents of each Markdown fenced code block.
phmdoctest.tool.fenced_block_nodes(fp: IO[str]) → List[commonmark.node.Node]

Get markdown fenced code blocks as list of Node objects.

Deprecation Watch: This function may be labelled as deprecated in a future version of phmdoctest. It returns a data type defined by the commonmark package.

Parameters:fp – file object returned by open().
Returns:List of commonmark.node.Node objects.

Get elements from test suite JUnit XML output

phmdoctest.tool.extract_testsuite(junit_xml_string: str) → Tuple[Optional[xml.etree.ElementTree.Element], List[xml.etree.ElementTree.Element]]

Return testsuite tree and list of failing trees from JUnit XML.

Parameters:junit_xml_string – String containing JUnit xml returned by pytest or phmdoctest.simulator.run_and_pytest().
Returns:tuple testsuite tree, list of failed test case trees

Test phmdoctest from within a python script

phmdoctest.simulator.run_and_pytest(well_formed_command: str, pytest_options: Optional[List[str]] = None, junit_family: Optional[str] = None) → phmdoctest.simulator.SimulatorStatus

Simulate a phmdoctest command, optionally run pytest.

If a filename is provided by the --outfile option, the command is rewritten replacing the OUTFILE with a path to a temporary directory and a synthesized filename.

To run pytest on an --outfile, pass a list of zero or more pytest_options. pytest is run in a subprocess.

The PYPI package pytest must be installed separately since pytest is not required to install phmdoctest. Use this command: pip install pytest

Returns SimulatorStatus object. SimulatorStatus.runner_status is the CliRunner.invoke return value.

If an outfile is streamed to stdout a copy of it is found in simulator_status.runner_status.stdout.

If calling run_and_pytest() from a pytest file, try adding the pytest option --capture=tee-sys to the command running pytest on the file.

For example on a checkout of phmdoctest the command line:

python -m pytest tests -v --capture=tee-sys

will print the outputs from the invocations of pytest on the --outfile written to the temporary directory. A wild guess would be that the subprocess inherited changes made to the parent by –capture=tee-sys.

  • well_formed_command
    • starts with phmdoctest
    • followed by MARKDOWN_FILE
    • ends with --outfile OUTFILE (if needed)
    • all other options are between MARKDOWN_FILE and --outfile for example: phmdoctest MARKDOWN_FILE --skip FIRST --outfile OUTFILE
  • pytest_options – List of strings like this: ['--doctest-modules', '-v']. Set to empty list to run pytest with no options. Set to None to skip pytest.
  • junit_family – Configures the format of the Pytest generated JUnit XML string returned in SimulatorStatus. The value is used for the Pytest configuration option of the same name. Set to None or the empty string to skip XML generation.

SimulatorStatus containing runner_status, outfile, pytest_exit_code, and generated JUnit XML.