Developer Interface

Main Interface

Examples for the most relevant api functions can be viewed in the test file. md_toc’s API uses type hints instead of assertions to check input and output types.

md_toc.get_atx_heading(line: str, keep_header_levels: int = 3, parser: str = 'github', no_links: bool = False) list

Given a line extract the link label and its type.

Parameters
  • line (str) – the line to be examined. This string may include newline characters in between.

  • keep_header_levels (int) – the maximum level of headers to be considered as such when building the table of contents. Defaults to 3.

  • parser (str) – decides rules on how to generate the anchor text. Defaults to github.

  • no_links (bool) – disables the use of links.

Returns

struct, a list of dictionaries with header type (int) and header text trimmed (str) keys. Both values are set to None if the line does not contain header elements according to the rules of the selected markdown parser.

Return type

list

Raises

GithubEmptyLinkLabel or GithubOverflowCharsLinkLabel or a built-in exception.

Note

license B applies for the github part. See docs/copyright_license.rst

md_toc.get_md_header(header_text_line: str, header_duplicate_counter: dict, keep_header_levels: int = 3, parser: str = 'github', no_links: bool = False) dict

Build a data structure with the elements needed to create a TOC line.

Parameters
  • header_text_line (str) – a single markdown line that needs to be transformed into a TOC line. This line may include nmultiple newline characters in between.

  • header_duplicate_counter (dict) – a data structure that contains the number of occurrencies of each header anchor link. This is used to avoid duplicate anchor links and it is meaningful only for certain values of parser.

  • keep_header_levels (int) – the maximum level of headers to be considered as such when building the table of contents. Defaults to 3.

  • parser (str) – decides rules on how to generate anchor links. Defaults to github.

Returns

a list with elements None if the input line does not correspond to one of the designated cases or a list of data structures containing the necessary components to create a table of contents.

Return type

list

Raises

a built-in exception.

Note

This works like a wrapper to other functions.

md_toc.build_toc_line(toc_line_no_indent: str, no_of_indentation_spaces: int = 0) str

Build the TOC line.

Parameters
  • toc_line_no_indent (str) – the TOC line without indentation.

  • no_of_indentation_spaces (int) – the number of indentation spaces. Defaults to 0.

Returns

toc_line, a single line of the table of contents.

Return type

str

Raises

a built-in exception.

md_toc.increase_index_ordered_list(header_type_count: dict, header_type_prev: int, header_type_curr: int, parser: str = 'github')

Compute the current index for ordered list table of contents.

Parameters
  • header_type_count (dict) – the count of each header type.

  • header_type_prev (int) – the previous type of header (h[1,…,Inf]).

  • header_type_curr (int) – the current type of header (h[1,…,Inf]).

  • parser (str) – decides rules on how to generate ordered list markers. Defaults to github.

Returns

None

Return type

None

Raises

GithubOverflowOrderedListMarker or a built-in exception.

Apply the specified slug rule to build the anchor link.

Parameters
  • header_text_trimmed (str) – the text that needs to be transformed in a link.

  • header_duplicate_counter (dict) – a data structure that keeps track of possible duplicate header links in order to avoid them. This is meaningful only for certain values of parser.

  • parser (str) – decides rules on how to generate anchor links. Defaults to github.

Returns

None if the specified parser is not recognized, or the anchor link, otherwise.

Return type

str

Raises

a built-in exception.

md_toc.build_toc(filename: str, ordered: bool = False, no_links: bool = False, no_indentation: bool = False, no_list_coherence: bool = False, keep_header_levels: int = 3, parser: str = 'github', list_marker: str = '-', skip_lines: int = 0, constant_ordered_list: bool = False, newline_string: str = '\n') str

Build the table of contents of a single file.

Parameters
  • filename (str) – the file that needs to be read.

  • ordered (bool) – decides whether to build an ordered list or not. Defaults to False.

  • no_links (bool) – disables the use of links. Defaults to False.

  • no_indentation (bool) – disables indentation in the list. Defaults to False.

  • keep_header_levels (int) – the maximum level of headers to be considered as such when building the table of contents. Defaults to 3.

  • parser (str) – decides rules on how to generate anchor links. Defaults to github.

  • list_marker (str) – a string that contains some of the first characters of the list element. Defaults to -.

  • skip_lines (int) – the number of lines to be skipped from the start of file before parsing for table of contents. Defaults to 0`.

  • constant_ordered_list (bool) – use a single integer as list marker. This sets ordered to True.

  • newline_string (str) – the newline separator. Defaults to os.linesep.

Returns

toc, the corresponding table of contents of the file.

Return type

str

Raises

a built-in exception.

md_toc.build_multiple_tocs(filenames: list, ordered: bool = False, no_links: bool = False, no_indentation: bool = False, no_list_coherence: bool = False, keep_header_levels: int = 3, parser: str = 'github', list_marker: str = '-', skip_lines: int = 0, constant_ordered_list: bool = False, newline_string: str = '\n') list

Parse files by line and build the table of contents of each file.

Parameters
  • filenames (list) – the files that needs to be read.

  • ordered (bool) – decides whether to build an ordered list or not. Defaults to False.

  • no_links (bool) – disables the use of links. Defaults to False.

  • no_indentation (bool) – disables indentation in the list. Defaults to False.

  • keep_header_levels (int) – the maximum level of headers to be considered as such when building the table of contents. Defaults to 3.

  • parser (str) – decides rules on how to generate anchor links. Defaults to github.

  • skip_lines (int) – the number of lines to be skipped from the start of file before parsing for table of contents. Defaults to 0`.

  • list_marker (str) – a string that contains some of the first characters of the list element. Defaults to -.

  • constant_ordered_list (bool) – use a single integer as list marker. This sets ordered to True.

  • newline_string (str) – the newline separator. Defaults to os.linesep.

Returns

toc_struct, the corresponding table of contents for each input file.

Return type

list

Raises

a built-in exception.

Warning

In case of ordered TOCs you must explicitly pass one of the supported ordered list markers.

md_toc.write_string_on_file_between_markers(filename: str, string: str, marker: str, newline_string: str = '\n')

Write the table of contents on a single file.

Parameters
  • filename – the file that needs to be read or modified.

  • string (str) – the string that will be written on the file.

  • marker (str) – a marker that will identify the start and the end of the string.

  • newline_string (str) – the new line separator. Defaults to os.linesep.

Returns

None

Return type

None

Raises

StdinIsNotAFileToBeWritten or an fpyutils exception or a built-in exception.

md_toc.write_strings_on_files_between_markers(filenames: list, strings: list, marker: str, newline_string: str = '\n')

Write the table of contents on multiple files.

Parameters
  • filenames (list) – the files that needs to be read or modified.

  • strings (list) – the strings that will be written on the file. Each string is associated with one file.

  • marker (str) – a marker that will identify the start and the end of the string.

  • newline_string (str) – the new line separator. Defaults to os.linesep.

Returns

None

Return type

None

Raises

an fpyutils exception or a built-in exception.

md_toc.init_indentation_log(parser: str = 'github', list_marker: str = '-') dict

Create a data structure that holds list marker information.

Parameters
  • parser (str) – decides rules on how compute indentations. Defaults to github.

  • list_marker (str) – a string that contains some of the first characters of the list element. Defaults to -.

Returns

indentation_log, the data structure.

Return type

dict

Raises

a built-in exception.

md_toc.compute_toc_line_indentation_spaces(header_type_curr: int = 1, header_type_prev: int = 0, parser: str = 'github', ordered: bool = False, list_marker: str = '-', indentation_log: dict = {1: {'indentation spaces': 0, 'index': 0, 'list marker': '-'}, 2: {'indentation spaces': 0, 'index': 0, 'list marker': '-'}, 3: {'indentation spaces': 0, 'index': 0, 'list marker': '-'}, 4: {'indentation spaces': 0, 'index': 0, 'list marker': '-'}, 5: {'indentation spaces': 0, 'index': 0, 'list marker': '-'}, 6: {'indentation spaces': 0, 'index': 0, 'list marker': '-'}}, index: int = 1)

Compute the number of indentation spaces for the TOC list element.

Parameters
  • header_type_curr (int) – the current type of header (h[1,…,Inf]). Defaults to 1.

  • header_type_prev (int) – the previous type of header (h[1,…,Inf]). Defaults to 0.

  • parser (str) – decides rules on how compute indentations. Defaults to github.

  • ordered (bool) – if set to True, numbers will be used as list ids instead of dash characters. Defaults to False.

  • list_marker (str) – a string that contains some of the first characters of the list element. Defaults to -.

  • indentation_log (dict) – a data structure that holds list marker information for ordered lists. Defaults to init_indentation_log('github', '.').

  • index (int) – a number that will be used as list id in case of an ordered table of contents. Defaults to 1.

Returns

None

Return type

None

Raises

a built-in exception.

Warning

In case of ordered TOCs you must explicitly pass one of the supported ordered list markers.

md_toc.build_toc_line_without_indentation(header: dict, ordered: bool = False, no_links: bool = False, index: int = 1, parser: str = 'github', list_marker: str = '-') str

Return a list element of the table of contents.

Parameters
  • header (dict) – a data structure that contains the original text, the trimmed text and the type of header.

  • ordered (bool) – if set to True, numbers will be used as list ids, otherwise a dash character. Defaults to False.

  • no_links (bool) – disables the use of links. Defaults to False.

  • index (int) – a number that will be used as list id in case of an ordered table of contents. Defaults to 1.

  • parser (str) – decides rules on how compute indentations. Defaults to github.

  • list_marker (str) – a string that contains some of the first characters of the list element. Defaults to -.

Returns

toc_line_no_indent, a single line of the table of contents without indentation.

Return type

str

Raises

a built-in exception.

Warning

In case of ordered TOCs you must explicitly pass one of the supported ordered list markers.

md_toc.is_valid_code_fence_indent(line: str, parser: str = 'github') bool

Determine if the given line has valid indentation for a code block fence.

Parameters
  • line (str) – a single markdown line to evaluate.

  • parser (str) – decides rules on how to generate the anchor text. Defaults to github.

Returns

True if the given line has valid indentation or False otherwise.

Return type

bool

Raises

a built-in exception.

md_toc.is_opening_code_fence(line: str, parser: str = 'github')

Determine if the given line is possibly the opening of a fenced code block.

Parameters
  • line (str) – a single markdown line to evaluate.

  • parser (str) – decides rules on how to generate the anchor text. Defaults to github.

Returns

None if the input line is not an opening code fence. Otherwise, returns the string which will identify the closing code fence according to the input parsers’ rules.

Return type

Optional[str]

Raises

a built-in exception.

md_toc.is_closing_code_fence(line: str, fence: str, is_document_end: bool = False, parser: str = 'github') bool

Determine if the given line is the end of a fenced code block.

Parameters
  • line (str) – a single markdown line to evaluate.

  • is_document_end (bool) – This variable tells the function that the end of the file is reached. Defaults to False.

  • parser (str) – decides rules on how to generate the anchor text. Defaults to github.

Paramter fence

a sequence of backticks or tildes marking the start of the current code block. This is usually the return value of the is_opening_code_fence function.

Returns

True if the line ends the current code block. False otherwise.

Return type

bool

Raises

a built-in exception.

md_toc.init_indentation_status_list(parser: str = 'github')

Create a data structure that holds the state of indentations.

Parameters

parser (str) – decides the length of the list. Defaults to github.

Returns

indentation_list, a list that contains the state of indentations given a header type.

Return type

list

Raises

a built-in exception.

md_toc.toc_renders_as_coherent_list(header_type_curr: int = 1, header_type_first: int = 1, indentation_list: list = [False, False, False, False, False, False], parser: str = 'github') bool

Check if the TOC will render as a working list.

Parameters
  • header_type_curr (int) – the current type of header (h[1,…,Inf]).

  • header_type_first (int) – the type of header first encountered (h[1,…,Inf]). This must correspond to the one with the least indentation.

  • parser (str) – decides rules on how to generate ordered list markers.

Returns

renders_as_list

Return type

bool

Raises

a built-in exception.

md_toc.remove_html_tags(line: str, parser: str = 'github') str

Remove HTML tags.

Parameters
  • line (str) – a string.

  • parser (str) – decides rules on how to remove HTML tags. Defaults to github.

Returns

the input string without HTML tags.

Return type

str

Raises

a built-in exception.

md_toc.remove_emphasis(line: str, parser: str = 'github') list

Remove markdown emphasis.

Parameters
  • line (str) – a string.

  • parser (str) – decides rules on how to find delimiters. Defaults to github.

Returns

the input line without emphasis.

Return type

str

Raises

a built-in exception.

Note

Backslashes are preserved.

md_toc.replace_and_split_newlines(line: str) list

Replace all the newline characters with line feeds and separate the components.

Parameters

line (str) – a string.

Returns

a list of newline separated strings.

Return type

list

Raises

a built-in exception.

md_toc.filter_indices_from_line(line: str, ranges: list) str

Given a line and a Python ranges, remove the characters in the ranges.

Parameters
  • line (str) – a string.

  • ranges (list) – a list of Python ranges.

Returns

the line without the specified indices.

Return type

str

Raises

a built-in exception.

Exceptions

exception md_toc.GithubOverflowCharsLinkLabel

Cannot parse link label.

exception md_toc.GithubEmptyLinkLabel

The link lables contains only whitespace characters or is empty.

exception md_toc.GithubOverflowOrderedListMarker

The ordered list marker number is too big.

exception md_toc.StdinIsNotAFileToBeWritten

stdin cannot be written onto.

exception md_toc.TocDoesNotRenderAsCoherentList

TOC list indentations are either wrong or not what the user intended.

exception md_toc.StringCannotContainNewlines

The specified string cannot contain newlines.

exception md_toc.CannotTreatUnicodeString

Cannot treat unicode string.

Note

This exception is deprecated and will be removed in the next major release.