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') snake.md.Paragraph ¶
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) snake.md.Element ¶
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.)
- Returns
the Element added to the Document
- add_header(text: str, level: int = 1) snake.md.Header ¶
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
- Returns
the Header which was added to the Document
- add_horizontal_rule() snake.md.HorizontalRule ¶
A convenience method which adds a horizontal rule to the document.
- add_ordered_list(items: Iterable[str]) snake.md.MDList ¶
A convenience method which adds a simple ordered list to the document.
- Parameters
items (Iterable[str]) – a “list” of strings
- add_paragraph(text: str) snake.md.Paragraph ¶
A convenience method which adds a simple paragraph of text to the document.
- Parameters
text (str) – any arbitrary text
- add_quote(text: str) snake.md.Paragraph ¶
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]]) snake.md.Table ¶
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() snake.md.TableOfContents ¶
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. The table itself is lazy loaded, so it always captures all of the header elements regardless of when the document is rendered.
- add_unordered_list(items: Iterable[str]) snake.md.MDList ¶
A convenience method which adds a simple unordered list to the document.
- Parameters
items (Iterable[str]) – a “list” of strings
- check_for_errors() None ¶
A convenience method which can be used to verify the integrity of the document. Results will be printed to standard out.
- 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 called by __str__ for all classes which inherit Element.
- Raises
NotImplementedError – interface method never to be implemented
- Returns
the element as a markdown string
- verify() snake.md.Verification ¶
Verifies that the element is valid markdown.
- Raises
NotImplementedError – interface method never to be implemented
- Returns
a verification object from the violator
- 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 (rounds to closest bound if out of range)
- 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
- verify() snake.md.Verification ¶
Verifies that the provided header is valid. This mainly returns errors associated with the InlineText element provided during instantiation.
- Returns
a verification object from the violator
- class snake.md.HorizontalRule¶
Bases:
snake.md.Element
A horizontal rule is a line separating different sections of a document. Horizontal rules really only come in one form, so there are no settings to adjust.
- render() str ¶
Renders the horizontal rule using the three dash syntax.
- Returns
the horizontal rule as a markdown string
- verify() snake.md.Verification ¶
Verifies the structure of the HorizontalRule element. Because there is no way to customize this object, it is always valid. Therefore, this method returns an empty Verification object.
- Returns
a verification object from the violator
- 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.
- is_text() bool ¶
Checks if this InlineText is a text-only element. If not, it must be an image, a URL, or an inline code snippet.
- Returns
True if this is a text-only element; False otherwise
- 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() snake.md.Verification ¶
Verifies that the InlineText object is valid.
- Returns
a verification object containing any errors that may have occured
- verify_url() bool ¶
Verifies that a URL is a valid URL.
- Returns
True if the URL is valid; False otherwise
- 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
- verify() snake.md.Verification ¶
Verifies that the markdown list is valid. Mainly, this checks the validity of the containing InlineText items. The MDList class has no way to instantiate it incorrectly, beyond providing the wrong data types.
- Returns
a verification object from the violator
- 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
- insert_link(target: str, url: str) None ¶
A convenience method which inserts a link in the paragraph at the first instance of a target string.
- Parameters
target (str) – the string to link
url (str) – the url to link
- 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. If both flags are enabled, code takes precedence.
- Returns
the paragraph as a markdown string
- verify() snake.md.Verification ¶
Verifies that the Paragraph is valid.
- Returns
a verification object from the violator
- 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 the integrity of the markdown table. There are various ways a user could instantiate this object improperly. For example, they may provide a body with roes that are not all equal width. Likewise, the header may not match the width of the body. InlineText elements may also be malformed.
- Returns
a verification object from the violator
- class snake.md.TableOfContents(doc: snake.md.Document)¶
Bases:
snake.md.Element
A Table of Contents is an element containing an ordered list of all the <h2> headers in the document. This element can be placed in the document.
- Parameters
doc (Document) – a reference to the document containing this table of contents
- render() str ¶
Renders the table of contents using the Document reference.
- Returns
the table of contents as a markdown string
- verify() snake.md.Verification ¶
A Table of Contents is generated through a circular reference to the Document it contains. There is no way to instantiate this incorrectly.
- Returns
a verification object from the violator
- class snake.md.Verification¶
Bases:
object
Verification is a helper object for storing errors generated when creating a markdown document. This object is largely used internally to verify the contents of a document, but can be accessed through the various verify() methods throughout the library by the user. A convenience method is provided in Document for listing all of the errors. Otherwise, a handful of methods are available here for interacting with the Verification object directly.
- absorb(verification: snake.md.Verification) None ¶
Absorbs an existing verification object in self. This is helpful when you have many verification objects that you’d like to aggregate.
- Parameters
verification (Verification) – the verification object to absorb
- add_error(violator: object, error: str) None ¶
Documents a verification error.
- Parameters
violator (object) – the object which produced the error
error (str) – the error message detailing the error
- passes_inspection() bool ¶
Assuming this object has already been used to verify something, this function will determine if that verificatioc succeeded.
- Returns
True if there are no errors; False otherwise