Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

Create markdown formatted text

Project description

========================
Markdown_strings package
========================

Markdown is a markup language with plain text formatting syntax. This package
allows the creation of markdown-compliant strings. The following is a summary
of features with usage examples.

Note: asterisk and underscores are escaped for all functions that do not format
to code (inline_code and code_block).

Standard markdown features
==========================

Header
------

Return a header of specified level.

Keyword arguments:
style -- Specifies the header style (default atx). The "atx" style uses
hash signs, and has 6 levels. The "setext" style uses dashes or equals
signs for headers of levels 1 and 2 respectively, and is limited to
those two levels.

Specifying a level outside of the style's range results in a ValueError.
::

>>> header("Main Title", 1)
'# Main Title'
>>> header("Smaller subtitle", 4)
'#### Smaller subtitle'
>>> header("Setext style", 2, "setext")
'Setext style\n---'


Italics
-------

Return italics formatted text.
::

>>> italics("This text is italics")
'_This text is italics_'


Bold
----

Return bold formatted text.
::

>>> bold("This text is bold")
'**This text is bold**'


Inline code
-----------

Return formatted inline code.
::

>>> inline_code("This text is code")
'`This text is code`'


Code block
----------

Return a code block.

If a language is specified a fenced code block is produced, otherwise the
block is indented by four spaces.

Keyword arguments:
language -- Specifies the language to fence the code in (default blank).
::

>>> code_block("This is a simple codeblock.")
' This is a simple codeblock.'
>>> code_block("This is a simple codeblock.\\nBut it has a linebreak!")
' This is a simple codeblock.\\n But it has a linebreak!'
>>> code_block("This block of code has a specified language.", "python")
'```python\\nThis block of code has a specified language.\\n```'
>>> code_block("So\\nmany\\nlinebreaks.", "python")
'```python\\nSo\\nmany\\nlinebreaks.\\n```'


Link
----

Return an inline link.
::

>>> link ("This is a link", "https://github.com/abactel/markdown_strings")
'[This is a link](https://github.com/abactel/markdown_strings)'


Image
-----

Return an inline image.

Keyword arguments:
title -- Specify the title of the image, as seen when hovering over it.
::

>>> image("This is an image", "https://tinyurl.com/bright-green-tree")
'![This is an image](https://tinyurl.com/bright-green-tree)'
>>> image("This is an image", "https://tinyurl.com/bright-green-tree", "tree")
'![This is an image](https://tinyurl.com/bright-green-tree) "tree"'


Unordered list
--------------

Return an unordered list from an array.
::

>>> unordered_list(["first", "second", "third", "fourth"])
'- first\\n- second\\n- third\\n- fourth'
>>> unordered_list([1, 2, 3, 4, 5])
'- 1\\n- 2\\n- 3\\n- 4\\n- 5'


Ordered list
------------

Return an ordered list from an array.
::

>>> ordered_list(["first", "second", "third", "fourth"])
'1. first\\n2. second\\n3. third\\n4. fourth'


Blockquote
----------

Return a blockquote.
::

>>> blockquote("A simple blockquote")
'> A simple blockquote'


Horizontal rule
---------------

Return a horizontal rule.

Keyword arguments:
length -- Specifies the length of the rule (default 79, minimum 3).

style -- Character used for the rule (may be either "_" or "*").

If the length is too low, or the style is invalid, a ValueError is raised.
::

>>> horizontal_rule()
'_______________________________________________________________________________'
>>> horizontal_rule(length=5, style="*")
'***'
"""


Non-standard markdown
=====================

Strikethrough
-------------

Return text with strike-through formatting.
::

>>> strikethrough("This is a lie")
'~This is a lie~'


Task list
---------

Return a task list.

The task_array should be 2-dimensional; the first item should be the task
text, and the second the boolean completion state.
::

>>> task_list([["Be born", True], ["Be dead", False]])
'- [X] Be born\\n- [ ] Be dead'

When displayed using `print`, this will appear as:
::

- [X] Be born
- [ ] Be dead


Table row
---------

Return a single table row.

Keyword arguments:

pad -- The pad should be an array of the same size as the input text array.
It will be used to format the row's padding.
::

>>> table_row(["First column", "Second", "Third"])
'| First column | Second | Third |'
>>> table_row(["First column", "Second", "Third"], [10, 10, 10])
'| First column | Second | Third |'


Delimiter row
-------------

Return a delimiter row for use in a table.
::

>>> table_delimiter_row(3)
'| --- | --- | --- |'


Table from columns
------------------

Return a formatted table, generated from arrays representing columns.

The function requires a 2-dimensional array, where each array is a column
of the table. This will be used to generate a formatted table in string
format. The number of items in each columns does not need to be consitent.
::

>>> table_from_columns([["Name", "abactel", "Bob"], ["User", "4b4c73l", ""]])
'| Name | User |\\n| ------- | ------- |\\n| abactel | 4b4c73l |\\n| Bob | |'

When displayed using `print`, this will appear as:
::

| Name | User |
| ------- | ------- |
| abactel | 4b4c73l |
| Bob | |


Helper functions
================

Return text with formatting escaped

Markdown requires a backslash before literal inderscores or asterisk, to avoid
formatting to bold or italics.
::

>>> esc_format("Normal text")
'Normal text'
>>> esc_format("Text with **bold**")
'Text with \\\*\\\*bold\\\*\\\*'
>>> esc_format("Text with _italics_")
'Text with \\\_italics\\\_'
>>> esc_format("Text with _**complicated** formatting_")
'Text with \\\_\\\*\\\*complicated\\\*\\\* formatting\\\_'
"""


Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for markdown-strings, version 3.1.1
Filename, size File type Python version Upload date Hashes
Filename, size markdown_strings-3.1.1-py2.py3-none-any.whl (9.4 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size markdown_strings-3.1.1.tar.gz (6.4 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page