snake package

The snake package is a collection of submodules for generating markdown files with Python.

Submodules

The snake package contains two main submodules: md and readme. The readme submodule is what is used to generate the project README. The md submodule provides all the markdown utilities needed to create a markdown file using Python only.

snake.md module

The md submodule contains all of the functionality for generating markdown files with Python. In general, library is straightforward to use. To create a new markdown file, create a Document as follows:

from snake.md import Document
doc = Document("MyProject")

From there, any number of document methods can be used to generate a markdown file. For example, we can create a header and a paragraph as follows:

doc.add_header("Welcome to MyProject!")
doc.add_paragraph("Learn about MyProject here.")

Then, when you’re ready to output your document, you can do that as follows:

doc.output_page()

See the remainder of this section for details on all the functionality provided in snake.md.

class snake.md.Document(name: str)

Bases: object

A document represents a markdown file. Documents store a collection of elements which are appended with new lines between to generate the markdown document. Document methods are intended to provided convenience when generating a markdown file. However, the functionality is not exhaustive. To get the full range of markdown functionality, you can take advantage of the add_element() function to provide custom markdown elements.

Parameters

name – the name of the document

add_code(code: str, lang: str = 'generic') None

A convenience method which adds a code block to the document.

Parameters
  • code (str) – a preformatted code string

  • lang (str) – the language for syntax highlighting

add_element(element: snake.md.Element) None

A generic function for appending elements to the document. Use this function when you want a little more control over what the output looks like.

Parameters

element (Element) – a markdown object (e.g., Table, Header, etc.)

add_header(text: str, level: int = 1) None

A convenience method which adds a simple header to the document.

Parameters
  • text (str) – the text for the header

  • level (int) – the level of the header from 1 to 6

add_ordered_list(items: Iterable[str]) None

A convenience method which adds a simple ordered list to the document.

Parameters

items (Iterable[str]) – a “list” of strings

add_paragraph(text: str) None

A convenience method which adds a simple paragraph of text to the document.

Parameters

text (str) – any arbitrary text

add_quote(text: str) None

A convenience method which adds a blockquote to the document.

Parameters

text (str) – the text to be quoted

add_table(header: Iterable[str], data: Iterable[Iterable[str]]) None

A convenience method which adds a simple table to the document.

Parameters
  • header (Iterable[str]) – a “list” of strings

  • data (Iterable[Iterable[str]]) – a “list” of “lists” of strings

add_table_of_contents() None

A convenience method which creates a table of contents. This function can be called where you want to add a table of contents to your document. However, be aware that the table of contents uses lazy loading, so it can only be rendered once.

add_unordered_list(items: Iterable[str]) None

A convenience method which adds a simple unordered list to the document.

Parameters

items (Iterable[str]) – a “list” of strings

output_page(dump_dir: str = '') None

Generates the markdown file.

Parameters

dump_dir (str) – the path to where you want to dump the file

render() str

Renders the markdown document from a list of elements.

Returns

the document as a markdown string

scramble() None

A silly method which mixes all of the elements in this document in a random order.

class snake.md.Element

Bases: object

An element is defined as a standalone section of a markdown file. All elements are to be surrounded by empty lines. Examples of elements include paragraphs, headers, tables, and lists.

render() str

Renders the element as a markdown string. This function is to be called by __str__() of the child class.

Raises

NotImplementedError – interface method never to be implemented

Returns

the element as a markdown string

verify()

Verifies that the element is valid markdown. TODO: figure out how this function should work.

Raises

NotImplementedError – interface method never to be implemented

class snake.md.Header(text: snake.md.InlineText, level: int)

Bases: snake.md.Element

A header is a text element which serves as the title for a new section of a document. Headers come in six main sizes which correspond to the six headers sizes in HTML (e.g., <h1>).

Parameters
  • text (InlineText) – the header text

  • level (int) – the header level between 1 and 6

demote() None

Demotes a header down a level. Fails silently if the header is already at the lowest level (i.e., <h6>).

promote() None

Promotes a header up a level. Fails silently if the header is already at the highest level (i.e., <h1>).

render() str

Renders the header in markdown according to the level provided.

Returns

the header as a markdown string

class snake.md.InlineText(text: str, url: Optional[str] = None, bold: bool = False, italics: bool = False, code: bool = False, image: bool = False)

Bases: object

The basic unit of text in markdown. All components which contain text are built using this class instead of strings directly. That way, those elements capture all styling information.

Parameters
  • text (str) – the inline text to render

  • url (str) – the link associated with the inline text

  • bold (bool) – the bold state of the inline text; set to True to render bold inline text (i.e., True -> bold)

  • italics (bool) – the italics state of the inline text; set to True to render inline text in italics (i.e., True -> italics)

  • code (bool) – the italics state of the inline text; set to True to render inline text as code (i.e., True -> code)

  • image (bool) – the image state of the inline text; set to True to render inline text as an image; must include url parameter to render

bold() None

Adds bold styling to self.

render() str

Renders self as a string. In this case, inline text can represent many different types of data from stylized text to inline code to links and images.

Returns

the InlineText object as a string

unbold() None

Removes bold styling from self.

verify() bool
class snake.md.MDList(items: Iterable[Union[snake.md.InlineText, snake.md.MDList]], ordered: bool = False)

Bases: snake.md.Element

A markdown list is a standalone list that comes in two varieties: ordered and unordered.

Parameters
  • items – a “list” of objects to be rendered as a list

  • ordered – the ordered state of the list; set to True to render an ordered list (i.e., True -> 1. item)

render() str

Renders the markdown list according to the settings provided. For example, if the the ordered flag is set, an ordered list will be rendered in markdown.

Returns

the list as a markdown string

class snake.md.Paragraph(content: Iterable[snake.md.InlineText], code: bool = False, lang: str = 'generic', quote: bool = False)

Bases: snake.md.Element

A paragraph is a standalone element of text. Paragraphs can be formatted in a variety of ways including as code and blockquotes.

Parameters
  • content (Iterable[InlineText]) – a “list” of text objects to render as a paragraph

  • code (bool) – the code state of the paragraph; set True to convert the paragraph to a code block (i.e., True -> `code`)

  • lang (str) – the language of the code snippet; invalid without the code flag set to True

  • quote (bool) – the quote state of the paragraph; set True to convert the paragraph to a blockquote (i.e., True -> > quote)

add(text: snake.md.InlineText) None

Adds a text object to the paragraph.

Parameters

text – a custom text element

render() str

Renders the paragraph as markdown according to the settings provided. For example, if the code flag is enabled, the paragraph will be rendered as a code block.

Returns

the paragraph as a markdown string

class snake.md.Table(header: Iterable[snake.md.InlineText], body: Iterable[Iterable[snake.md.InlineText]])

Bases: snake.md.Element

A table is a standalone element of rows and columns. Data is rendered according to underlying InlineText items.

Parameters
  • header – the header row of labels

  • body – the collection of rows of data

render() str

Renders a markdown table from a header “list” and a data set.

Returns

a table as a markdown string

verify()

Verifies that the element is valid markdown. TODO: figure out how this function should work.

Raises

NotImplementedError – interface method never to be implemented

snake.readme module

snake.readme.main() None

Generates the repo README.

Module contents