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