Md

Yuio’s primary format for higher-level io is Markdown (well, a reasonably rich subset of it).

Formatting markdown

class yuio.md.MdFormatter(theme: Theme, *, width: int | None = None, allow_headings: bool = True)

A simple markdown formatter suitable for displaying reach text in the terminal.

All CommonMark block markup is supported:

• headings:

  # Heading 1
  ## Heading 2
  

  Yuio has only two levels of headings. Headings past level two will look the same as level two headings (you can adjust theme to change this).

  If allow_headings is set to false, headings look like paragraphs.

• lists, numbered lists, quotes:

  -  List item 1,
  -  list item 2.
  
  1. Numbered list item 1,
  1. numbered list item 2.
  
  > Quoted text.
  

• fenced code blocks with minimal syntax highlighting (see SyntaxHighlighter):

  ```python
  for i in range(5, 8):
      print(
         f"Hello, world! "
         "This is {i}th day past the apocalypse."
     )
  ```
  

  Yuio supports python, traceback, and bash syntaxes.

Inline markdown only handles inline code blocks:

This is `code`. It will be rendered as code.
Other inline styles, such as _italic_, are not supported!

However, color tags are supported, so you can highlight text as follows:

This is <c b>bold text</c>. It will be rendered bold.

property width: int

Target width for soft-wrapping text.

format(s: str, /) → ColorizedString

Format a markdown document.

parse(s: str, /) → AstBase

Parse a markdown document and return an AST node.

Warning

This is an experimental API which can change within a minor release.

format_node(node: AstBase, /) → ColorizedString

Format a parsed markdown document.

Warning

This is an experimental API which can change within a minor release.

colorize(s: str, /, *, default_color: Color | str = Color(fore=None, back=None, bold=None, dim=None))

Parse and colorize contents of a paragraph.

Apply default_color to the entire paragraph, and process color tags and backticks within it.

Highlighting code

Yuio supports basic code highlighting; it is just enough to format help messages for CLI, and color tracebacks when an error occurs.

class yuio.md.SyntaxHighlighter

abstract property syntaxes: List[str]

List of syntax names that should be associated with this highlighter.

The first name in this list is a canonical syntax name, i.e. it will be used to look up colors in a theme.

property syntax: str

The primary syntax name for this highlighter.

This name is used to look up colors in a theme.

classmethod register_highlighter(highlighter: SyntaxHighlighter)

Register a highlighter in a global registry, and allow looking it up via the get_highlighter() method.

classmethod get_highlighter(syntax: str, /) → SyntaxHighlighter

Look up highlighter by a syntax name.

abstract highlight(theme: Theme, code: str, default_color: Color | str | None = None) → ColorizedString

Highlight the given code using the given theme.

Markdown AST

Warning

This is an experimental API which can change within a minor release.

class yuio.md.AstBase

Base class for all AST nodes that represent parsed markdown document.

dump(indent: str = '') → str

Dump an AST node into a lisp-like text representation.

class yuio.md.Text(lines: List[str])

Base class for all text-based AST nodes, i.e. paragraphs.

lines: List[str]

Text lines as parsed from the original document.

dump(indent: str = '') → str

Dump an AST node into a lisp-like text representation.

class yuio.md.Container(items: List[TAst])

Base class for all container-based AST nodes, i.e. list items or quotes.

This class works as a list of items. Usually it contains arbitrary AST nodes, but it can also be limited to specific kinds of nodes via its generic variable.

items: List[TAst]

Inner AST nodes in the container.

dump(indent: str = '') → str

Dump an AST node into a lisp-like text representation.

class yuio.md.Document(items: List[TAst])

Root node that contains the entire markdown document.

class yuio.md.ThematicBreak

Represents a visual break in text, a.k.a. an asterism.

class yuio.md.Heading(lines: List[str], level: int)

Represents a heading.

level: int

Level of the heading, 1-based.

class yuio.md.Paragraph(lines: List[str])

Represents a regular paragraph.

class yuio.md.Quote(items: List[TAst])

Represents a quotation block.

class yuio.md.Code(lines: List[str], syntax: str)

Represents a highlighted block of code.

syntax: str

Syntax indicator as parsed form the original document.

class yuio.md.ListItem(items: List[TAst], number: int | None)

A possibly numbered element of a list.

number: int | None

If present, this is the item’s number in a numbered list.

class yuio.md.List(items: List[TAst])

A collection of list items.