The Element API
For users who want a little more control over how their markdown is formatted, SnakeMD provides a low-level API constructed of elements.
Element Interface
- class snakemd.Element
Bases:
ABC
A generic element interface which provides a framework for all types of elements in the collection. In short, elements should be able to be verified.
- render() str
Renders the element as a markdown string. This function now just calls the __str__ method directly.
Deprecated since version 0.14.0: replaced with the default dunder method
__str__()
- Returns:
the element as a markdown string
- abstract verify() Verification
Verifies that the element is valid markdown.
- Returns:
a verification object from the violator
Elements are then broken down into two main types: block and inline.
Block Elements
SnakeMD block elements borrow from the idea of block-level elements
from HTML. And because Markdown documents are constructed from a
series of blocks, users of SnakeMD can seemlessly append their own
custom blocks using the add_block()
method. To make use
of this method, blocks must be imported and constructed manually,
like the following Heading example:
from snakemd import Heading
doc.add_block(Heading("Hello, World!", 2))
The remainder of this section introduces the Block interface as well as all of the Blocks currently available for use.
Block Interface
All markdown blocks inherit from the Block interface.
- class snakemd.Block
Bases:
Element
A block element in Markdown. A block is defined as a standalone element starting on a newline. Examples of blocks include paragraphs (i.e., <p>), headings (e.g., <h1>, <h2>, etc.), tables (i.e., <table>), and lists (e.g., <ol>, <ul>, etc.).
New in version 0.14.0: replaced the
Element
class
Verification
Warning
The verification object and its implementation throughout SnakeMD is in beta, and it should not be used to verify production markdown.
Because of the increase in control granted to users
by blocks, there are opportunities where invalid
markdown can be generated. In an attempt to provide
a method of verifying the structure of the markdown,
a verify()
method has been provided for all
elements. The result of a call to verify()
is a verification object which is defined as folows:
- class snakemd.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.
New in version 0.2.0.
- absorb(verification: 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
The remainder of this page outlines the various elements that can be added to a markdown document.
Code
- class snakemd.Code(code: str | snakemd.elements.Code, lang: str = 'generic')
Bases:
Block
A code block is a standalone block of syntax-highlighted code. Code blocks can have generic highlighting or highlighting based on their language.
New in version 0.15.0.
- verify() Verification
Verifies that the element is valid markdown.
- Returns:
a verification object from the violator
Heading
- class snakemd.Heading(text: Union[str, Inline, Iterable[snakemd.elements.Inline | str]], level: int)
Bases:
Block
A heading is a text block which serves as the title for a new section of a document. Headings come in six main sizes which correspond to the six headings sizes in HTML (e.g., <h1>).
- Parameters:
- demote() None
Demotes a heading down a level. Fails silently if the heading is already at the lowest level (i.e., <h6>).
- get_text() str
Returns the heading text free of any styling.
New in version 0.15.0.
- Returns:
the heading as a string
- promote() None
Promotes a heading up a level. Fails silently if the heading is already at the highest level (i.e., <h1>).
- verify() Verification
Verifies that the provided heading is valid. This mainly returns errors associated with the Inline element provided during instantiation.
New in version 0.2.0.
- Returns:
a verification object from the violator
HorizontalRule
- class snakemd.HorizontalRule
Bases:
Block
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.
New in version 0.2.0.
- verify() Verification
Verifies the structure of the HorizontalRule block. Because there is no way to customize this object, it is always valid. Therefore, this method returns an empty Verification object.
New in version 0.2.0.
- Returns:
a verification object from the violator
MDList
- class snakemd.MDList(items: Iterable[str | snakemd.elements.Inline | snakemd.elements.Paragraph | snakemd.elements.MDList], ordered: bool = False, checked: Union[None, bool, Iterable[bool]] = None)
Bases:
Block
A markdown list is a standalone list that comes in three varieties: ordered, unordered, and checked.
Changed in version 0.4.0: Expanded constructor to accept strings directly
- Parameters:
items (Iterable[str | Inline | Paragraph | MDList]) – a “list” of objects to be rendered as a list
ordered (bool) – the ordered state of the list; set to True to render an ordered list (i.e., True -> 1. item)
checked (None | bool | Iterable[bool]) – the checked state of the list; set to True, False, or an iterable of booleans to enable the checklist feature.
- verify() Verification
Verifies that the markdown list is valid. Mainly, this checks the validity of the containing Inline items. The MDList class has no way to instantiate it incorrectly, beyond providing the wrong data types.
New in version 0.2.0.
- Returns:
a verification object from the violator
Paragraph
- class snakemd.Paragraph(content: Iterable[snakemd.elements.Inline | str], code: bool = False, lang: str = 'generic', quote: bool = False)
Bases:
Block
A paragraph is a standalone block of text. Paragraphs can be formatted in a variety of ways including as code and blockquotes.
Changed in version 0.4.0: Expanded constructor to accept strings directly
- Parameters:
content (Iterable[Inline | str]) – 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`
)Deprecated since version 0.15.0: replaced in favor of the
Code
blocklang (str) –
the language of the code snippet; invalid without the code flag set to True
Deprecated since version 0.15.0: replaced in favor of the
Code
blockquote (bool) – the quote state of the paragraph; set True to convert the paragraph to a blockquote (i.e., True -> > quote)
- add(text: snakemd.elements.Inline | str) None
Adds a text object to the paragraph.
Changed in version 0.4.0: Allows adding of strings directly
- Parameters:
text – a custom Inline element
- insert_link(target: str, url: str, count: int = -1) Paragraph
A convenience method which inserts links in the paragraph for all matching instances of a target string. This method is modeled after
str.replace()
, so a count can be provided to limit the number of insertions. This method will not replace links of text that have already been linked. See replace_link() for that behavior.paragraph.insert_link("Here", "https://therenegadecoder.com")
New in version 0.2.0.
Changed in version 0.5.0: Changed function to insert links at all instances of target rather than just the first instance
- Parameters:
target (str) – the string to link
url (str) – the url to link
count (int) – the number of links to insert; defaults to -1 (all)
- Returns:
self
- is_text() bool
Checks if this Paragraph is a text-only block. If not, it must be a quote or code block.
New in version 0.3.0.
- Returns:
True if this is a text-only block; False otherwise
- replace(target: str, replacement: str, count: int = -1) Paragraph
A convenience method which replaces a target string with a string of the users choice. Like insert_link, this method is modeled after
str.replace()
of the standard library. As a result, a count can be provided to limit the number of strings replaced in the paragraph.New in version 0.5.0.
- Parameters:
target (str) – the target string to replace
replacement (str) – the Inline object to insert in place of the target
count (int) – the number of links to insert; defaults to -1
- Returns:
self
- replace_link(target: str, url: str, count: int = -1) Paragraph
A convenience method which replaces matching URLs in the paragraph with a new url. Like insert_link() and replace(), this method is also modeled after
str.replace()
, so a count can be provided to limit the number of links replaced in the paragraph. This method is useful if you want to replace existing URLs but don’t necessarily care what the anchor text is.New in version 0.7.0.
- Parameters:
target (str) – the string to link
url (str) – the url to link
count (int) – the number of links to replace; defaults to -1 (all)
- Returns:
self
- verify() Verification
Verifies that the Paragraph is valid.
New in version 0.2.0.
- Returns:
a verification object from the violator
- verify_urls() dict[str, bool]
Verifies all URLs in the paragraph. Results are returned in a dictionary where the URLs are mapped to their validity.
- Returns:
a dictionary of URLs mapped to their validity
Raw
- class snakemd.Raw(text: str)
Bases:
Block
Raw blocks allow a user to insert text into the Markdown document without an processing. Use this block to insert raw Markdown or other types of text (e.g., Jekyll frontmatter).
New in version 0.14.0.
- verify() Verification
Verifies that the element is valid markdown.
- Returns:
a verification object from the violator
Table
- class snakemd.Table(header: Iterable[str | Inline | Paragraph], body: Iterable[Iterable[str | Inline | Paragraph]] = [], align: Iterable[Align] = None, indent: int = 0)
Bases:
Block
A table is a standalone block of rows and columns. Data is rendered according to underlying Inline items.
Changed in version 0.4.0: Added optional alignment parameter and expanded constructor to accept strings
Changed in version 0.11.0: Added optional indentation parameter for the whole table
Changed in version 0.12.0: Made body parameter optional
- Parameters:
header – the header row of labels
body – the collection of rows of data
align – the column alignment
indent – indent size for the whole table
- class Align(value)
Bases:
Enum
Align is an enum only used by the Table class to specify the alignment of various columns in the table.
New in version 0.4.0.
- CENTER = 3
- LEFT = 1
- RIGHT = 2
- add_row(row: Iterable[str | snakemd.elements.Inline | snakemd.elements.Paragraph]) None
Adds a row to the end of table.
New in version 0.12.0.
- 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. Inline elements may also be malformed.
New in version 0.2.0.
- Returns:
a verification object from the violator
Inline Elements
One of the benefits of creating the Block elements directly over using the Document methods is the control users now have over the underlying structure and style. Now, instead of being bound to the string inputs, users can provide Inline elements directly. For example, maybe we want to be able to link a Heading. This is not exactly possible through the Document methods as even the returned Heading object has no support for linking. However, with Inline elements, we can create a custom Heading to our standards:
from snakemd import Heading
doc.add_block(Heading(Inline("Hello, World!", "https://snakemd.io"), 2))
The remainder of this section introduces the Inline class.
Inline
- class snakemd.Inline(text: str, url: Optional[str] = None, bold: bool = False, italics: bool = False, strikethrough: bool = False, code: bool = False, image: bool = False)
Bases:
Element
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.
New in version 0.14.0: replaced the
InlineText
- 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)
strikethrough (bool) – the strikethrough state of the inline text; set to True to render inline text with a strikethrough (i.e., True -> ~~strikethrough~~)
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() Inline
Adds bold styling to self.
Changed in version 0.7.0: Modified to return previous bold state
- Returns:
self
- is_text() bool
Checks if this Inline is a text-only element. If not, it must be an image, a URL, or an inline code snippet.
New in version 0.2.0.
- Returns:
True if this is a text-only element; False otherwise
- is_url() bool
Checks if the Inline object represents a URL.
- Returns:
True if the object has a URL; False otherwise
- link(url: str) Inline
Adds URL to self.
New in version 0.7.0.
- Parameters:
url (str) – the URL to apply to this Inline element
- Returns:
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.
Deprecated since version 0.14.0: replaced with the default dunder method
__str__()
- Returns:
the Inline object as a string
- reset() Inline
Removes all settings from self (e.g., bold, code, italics, url, etc.). All that will remain is the text itself.
New in version 0.7.0.
- Returns:
self
- unbold() Inline
Removes bold styling from self.
Changed in version 0.7.0: Modified to return previous bold state
- Returns:
self
- unstrikethrough() Inline
Remove strikethrough styling from self.
New in version 0.12.0.
- Returns:
self
- verify() Verification
Verifies that the Inline object is valid.
New in version 0.2.0.
- 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