# 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`).
## Installation
To install from pypi run
```sh
pip install markdown_strings
```
## Character escaping
Every standard function includes an optional keyword argument `esc`, set to
`True` by default. This parameter determines whether to escape characters in
the input text, thereby preventing them from triggering markdown formatting.
## 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. The number of dashes or equals signs is either the length
of the text, or 3.
Specifying a level outside of the style's range results in a ValueError.
```python
>>> header("Main Title", 1)
'# Main Title'
>>> header("Smaller subtitle", 4)
'#### Smaller subtitle'
>>> header("Setext style", 2, style="setext")
'Setext style\\n------------'
```
### Italics
Return italics formatted text.
```Python
>>> italics("This text is italics")
'_This text is italics_'
```
### Bold
Return bold formatted text.
```python
>>> bold("This text is bold")
'**This text is bold**'
```
### Inline code
Return formatted inline code.
```python
>>> 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).
````python
>>> 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.
```python
>>> link ("This is a link", "https://github.com/awesmubarak/markdown_strings")
'[This is a link](https://github.com/awesmubarak/markdown_strings)'
```
### Image
Return an inline image.
Keyword arguments:
- title -- Specify the title of the image, as seen when hovering over it.
```python
>>> image("This is an image", "https://avatars3.githubusercontent.com/u/24862378")
''
>>> image("This is an image", "https://avatars3.githubusercontent.com/u/24862378", "awes")
' "awes"'
```
### Unordered list
Return an unordered list from an list.
```python
>>> 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 list.
```python
>>> ordered_list(["first", "second", "third", "fourth"])
'1. first\\n2. second\\n3. third\\n4. fourth'
```
### Blockquote
Return a blockquote.
```python
>>> 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.
```python
>>> horizontal_rule()
'_______________________________________________________________________________'
>>> horizontal_rule(length=5, style="*")
'*****'
```
## Non-standard markdown
### Strikethrough
Return text with strike-through formatting.
```python
>>> strikethrough("This is a lie")
'~This is a lie~'
```
### Task list
Return a task list.
The task_list should be a 2-dimensional iterable; the first item should be the
task text and the second the boolean completion state.
```python
>>> task_list([["Be born", True], ["Be dead", False]])
'- [X] Be born\\n- [ ] Be dead'
```
### Table row
Return a single table row.
Keyword arguments:
- pad -- The pad should be an list of the same size as the input text list.
It will be used to format the row's padding.
```python
>>> 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.
Keyword arguments:
- column_lengths -- An iterable that specifies the length of each column.
```python
>>> table_delimiter_row(3)
'| --- | --- | --- |'
>>> table_delimiter_row(3, column_lengths=[4,5,6])
'| ---- | ----- | ------ |'
```
### Table
Return a formatted table, generated from lists representing columns.
The function requires a 2-dimensional list, where each list is a column
of the table. This will be used to generate a formatted table in string
format.
```python
>>> table([["1","2","3"], ["4","5","6"], ["7","8","9"]])
'| 1 | 4 | 7 |\\n| --- | --- | --- |\\n| 2 | 5 | 8 |\\n| 3 | 6 | 9 |'
>>> table([["Name", "Awes", "Bob"], ["User", "mub123", ""]])
'| Name | User |\\n| ---- | ------ |\\n| Awes | mub123 |\\n| Bob | |'
```
This table, when parsed, will look like this:
| Name | User |
| ---- | ------ |
| Awes | mub123 |
| Bob | |
### Table from rows
Return a formatted table, using each list as the list. The specifics are the
same as those for the table function.
```python
>>> table_from_rows([["1","2","3"],["4","5","6"],["7","8","9"]])
'| 1 | 2 | 3 |\\n| --- | --- | --- |\\n| 4 | 5 | 6 |\\n| 7 | 8 | 9 |'
```
## Helper functions
Return text with formatting escaped
Markdown requires a backslash before literal underscores or asterisk, to avoid
formatting to bold or italics.
Keyword arguments:
- esc -- Specifies if text should be escaped or not. This exists incase input text
should not be escaped
```python
>>> esc_format("Normal text", esc=True)
'Normal text'
>>> esc_format("Text with **bold**", esc=True) == r'Text with \\*\\*bold\\*\\*'
True
>>> esc_format("Text with _italics_", esc=True) == r'Text with \\_italics\\_'
True
>>> esc_format("Text with _**complicated** format_", esc=True) == r'Text with \\_\\*\\*complicated\\*\\* format\\_'
True
```
Raw data
{
"_id": null,
"home_page": "https://github.com/awesmubarak/markdown_strings",
"name": "markdown-strings",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "markdown md",
"author": "Awes Mubarak",
"author_email": "contact@awesmubarak.com",
"download_url": "https://files.pythonhosted.org/packages/72/d2/ef65d0f3c150bfc99f5c4a516ae57e7c3acddfaacc1196dd296b1299ea7f/markdown_strings-3.4.0.tar.gz",
"platform": null,
"description": "# Markdown_strings package\n\nMarkdown is a markup language with plain text formatting syntax. This package\nallows the creation of markdown-compliant strings. The following is a summary\nof features with usage examples.\n\nNote: asterisk and underscores are escaped for all functions that do not format\nto code (`inline_code` and `code_block`).\n\n## Installation\n\nTo install from pypi run\n\n```sh\npip install markdown_strings\n```\n\n## Character escaping\n\nEvery standard function includes an optional keyword argument `esc`, set to\n`True` by default. This parameter determines whether to escape characters in\nthe input text, thereby preventing them from triggering markdown formatting.\n\n## Standard markdown features\n\n### Header\n\nReturn a header of specified level.\n\nKeyword arguments:\n\n- style -- Specifies the header style (default atx). The \"atx\" style uses\n hash signs, and has 6 levels. The \"setext\" style uses dashes or equals\n signs for headers of levels 1 and 2 respectively, and is limited to\n those two levels. The number of dashes or equals signs is either the length\n of the text, or 3.\n\nSpecifying a level outside of the style's range results in a ValueError.\n\n```python\n>>> header(\"Main Title\", 1)\n'# Main Title'\n>>> header(\"Smaller subtitle\", 4)\n'#### Smaller subtitle'\n>>> header(\"Setext style\", 2, style=\"setext\")\n'Setext style\\\\n------------'\n```\n\n### Italics\n\nReturn italics formatted text.\n\n```Python\n>>> italics(\"This text is italics\")\n'_This text is italics_'\n```\n\n### Bold\n\nReturn bold formatted text.\n\n```python\n>>> bold(\"This text is bold\")\n'**This text is bold**'\n```\n\n### Inline code\n\nReturn formatted inline code.\n\n```python\n>>> inline_code(\"This text is code\")\n'`This text is code`'\n```\n\n### Code block\n\nReturn a code block.\n\nIf a language is specified a fenced code block is produced, otherwise the\nblock is indented by four spaces.\n\nKeyword arguments:\n\n- language -- Specifies the language to fence the code in (default blank).\n\n````python\n >>> code_block(\"This is a simple codeblock.\")\n ' This is a simple codeblock.'\n >>> code_block(\"This is a simple codeblock.\\\\nBut it has a linebreak!\")\n ' This is a simple codeblock.\\\\n But it has a linebreak!'\n >>> code_block(\"This block of code has a specified language.\", \"python\")\n '```python\\\\nThis block of code has a specified language.\\\\n```'\n >>> code_block(\"So\\\\nmany\\\\nlinebreaks.\", \"python\")\n '```python\\\\nSo\\\\nmany\\\\nlinebreaks.\\\\n```'\n````\n\n### Link\n\nReturn an inline link.\n\n```python\n>>> link (\"This is a link\", \"https://github.com/awesmubarak/markdown_strings\")\n'[This is a link](https://github.com/awesmubarak/markdown_strings)'\n```\n\n### Image\n\nReturn an inline image.\n\nKeyword arguments:\n\n- title -- Specify the title of the image, as seen when hovering over it.\n\n```python\n>>> image(\"This is an image\", \"https://avatars3.githubusercontent.com/u/24862378\")\n''\n>>> image(\"This is an image\", \"https://avatars3.githubusercontent.com/u/24862378\", \"awes\")\n' \"awes\"'\n```\n\n### Unordered list\n\nReturn an unordered list from an list.\n\n```python\n>>> unordered_list([\"first\", \"second\", \"third\", \"fourth\"])\n'- first\\\\n- second\\\\n- third\\\\n- fourth'\n>>> unordered_list([1, 2, 3, 4, 5])\n'- 1\\\\n- 2\\\\n- 3\\\\n- 4\\\\n- 5'\n```\n\n### Ordered list\n\nReturn an ordered list from an list.\n\n```python\n>>> ordered_list([\"first\", \"second\", \"third\", \"fourth\"])\n'1. first\\\\n2. second\\\\n3. third\\\\n4. fourth'\n```\n\n### Blockquote\n\nReturn a blockquote.\n\n```python\n>>> blockquote(\"A simple blockquote\")\n'> A simple blockquote'\n```\n\n### Horizontal rule\n\nReturn a horizontal rule.\n\nKeyword arguments:\n\n- length -- Specifies the length of the rule (default 79, minimum 3).\n- style -- Character used for the rule (may be either \"\\_\" or \"\\*\").\n\nIf the length is too low, or the style is invalid, a ValueError is raised.\n\n```python\n>>> horizontal_rule()\n'_______________________________________________________________________________'\n>>> horizontal_rule(length=5, style=\"*\")\n'*****'\n```\n\n## Non-standard markdown\n\n### Strikethrough\n\nReturn text with strike-through formatting.\n\n```python\n>>> strikethrough(\"This is a lie\")\n'~This is a lie~'\n```\n\n### Task list\n\nReturn a task list.\n\nThe task_list should be a 2-dimensional iterable; the first item should be the\ntask text and the second the boolean completion state.\n\n```python\n>>> task_list([[\"Be born\", True], [\"Be dead\", False]])\n'- [X] Be born\\\\n- [ ] Be dead'\n```\n\n### Table row\n\nReturn a single table row.\n\nKeyword arguments:\n\n- pad -- The pad should be an list of the same size as the input text list.\n It will be used to format the row's padding.\n\n```python\n>>> table_row([\"First column\", \"Second\", \"Third\"])\n'| First column | Second | Third |'\n>>> table_row([\"First column\", \"Second\", \"Third\"], [10, 10, 10])\n'| First column | Second | Third |'\n```\n\n### Delimiter row\n\nReturn a delimiter row for use in a table.\n\nKeyword arguments:\n\n- column_lengths -- An iterable that specifies the length of each column.\n\n```python\n>>> table_delimiter_row(3)\n'| --- | --- | --- |'\n>>> table_delimiter_row(3, column_lengths=[4,5,6])\n'| ---- | ----- | ------ |'\n```\n\n### Table\n\nReturn a formatted table, generated from lists representing columns.\n\nThe function requires a 2-dimensional list, where each list is a column\nof the table. This will be used to generate a formatted table in string\nformat.\n\n```python\n>>> table([[\"1\",\"2\",\"3\"], [\"4\",\"5\",\"6\"], [\"7\",\"8\",\"9\"]])\n'| 1 | 4 | 7 |\\\\n| --- | --- | --- |\\\\n| 2 | 5 | 8 |\\\\n| 3 | 6 | 9 |'\n\n>>> table([[\"Name\", \"Awes\", \"Bob\"], [\"User\", \"mub123\", \"\"]])\n'| Name | User |\\\\n| ---- | ------ |\\\\n| Awes | mub123 |\\\\n| Bob | |'\n```\n\nThis table, when parsed, will look like this:\n\n| Name | User |\n| ---- | ------ |\n| Awes | mub123 |\n| Bob | |\n\n### Table from rows\n\nReturn a formatted table, using each list as the list. The specifics are the\nsame as those for the table function.\n\n```python\n>>> table_from_rows([[\"1\",\"2\",\"3\"],[\"4\",\"5\",\"6\"],[\"7\",\"8\",\"9\"]])\n'| 1 | 2 | 3 |\\\\n| --- | --- | --- |\\\\n| 4 | 5 | 6 |\\\\n| 7 | 8 | 9 |'\n```\n\n## Helper functions\n\nReturn text with formatting escaped\n\nMarkdown requires a backslash before literal underscores or asterisk, to avoid\nformatting to bold or italics.\n\nKeyword arguments:\n\n- esc -- Specifies if text should be escaped or not. This exists incase input text\n should not be escaped\n```python\n>>> esc_format(\"Normal text\", esc=True)\n'Normal text'\n>>> esc_format(\"Text with **bold**\", esc=True) == r'Text with \\\\*\\\\*bold\\\\*\\\\*'\nTrue\n>>> esc_format(\"Text with _italics_\", esc=True) == r'Text with \\\\_italics\\\\_'\nTrue\n>>> esc_format(\"Text with _**complicated** format_\", esc=True) == r'Text with \\\\_\\\\*\\\\*complicated\\\\*\\\\* format\\\\_'\nTrue\n```\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Create markdown formatted text",
"version": "3.4.0",
"project_urls": {
"Homepage": "https://github.com/awesmubarak/markdown_strings"
},
"split_keywords": [
"markdown",
"md"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "92aaaa65cf458a5053d24237902e7a07a2f895f4d515aee53f73636deb4d36ea",
"md5": "20996394d526ca1e3fd66884d1f2a48d",
"sha256": "1a7e2a575b2af27482ccbe6a0efc3407f678ac5cece8654c36fd827ac540a631"
},
"downloads": -1,
"filename": "markdown_strings-3.4.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "20996394d526ca1e3fd66884d1f2a48d",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 8424,
"upload_time": "2024-05-03T15:40:02",
"upload_time_iso_8601": "2024-05-03T15:40:02.713038Z",
"url": "https://files.pythonhosted.org/packages/92/aa/aa65cf458a5053d24237902e7a07a2f895f4d515aee53f73636deb4d36ea/markdown_strings-3.4.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "72d2ef65d0f3c150bfc99f5c4a516ae57e7c3acddfaacc1196dd296b1299ea7f",
"md5": "45f8cb945134c22107d425cc5b473f26",
"sha256": "7574de0606160d7291ac2e1933a8ed47d31f0b49b674f128da1f548930c8578b"
},
"downloads": -1,
"filename": "markdown_strings-3.4.0.tar.gz",
"has_sig": false,
"md5_digest": "45f8cb945134c22107d425cc5b473f26",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7869,
"upload_time": "2024-05-03T15:40:04",
"upload_time_iso_8601": "2024-05-03T15:40:04.784887Z",
"url": "https://files.pythonhosted.org/packages/72/d2/ef65d0f3c150bfc99f5c4a516ae57e7c3acddfaacc1196dd296b1299ea7f/markdown_strings-3.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-03 15:40:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "awesmubarak",
"github_project": "markdown_strings",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "markdown-strings"
}
JSON
