mdutils package¶

Subpackages¶

Submodules¶

mdutils.mdutils module¶

Module mdutils

The available features are:

Create Headers, Til 6 sub-levels.
Auto generate a table of contents.
Create List and sub-list.
Create paragraph.
Generate tables of different sizes.
Insert Links.
Insert Code.
Place text anywhere using a marker.

class mdutils.mdutils.MdUtils(file_name: str, title: str = '', author: str = '')[source]¶

Bases: object

This class give some basic methods that helps the creation of Markdown files while you are executing a python code.

The __init__ variables are:

file_name: it is the name of the Markdown file.
author: it is the author fo the Markdown file.
header: it is an instance of Header Class.
textUtils: it is an instance of TextUtils Class.
title: it is the title of the Markdown file. It is written with Setext-style.
table_of_contents: it is the table of contents, it can be optionally created.
file_data_text: contains all the file data that will be written on the markdown file.

create_marker(text_marker: str) → str[source]¶

This will add a marker to file_data_text and returns the marker result in order to be used whenever

you need.

Markers allows to place them to the string data text and they can be replaced by a peace of text using place_text_using_marker method.

Parameters:	text_marker (str) – marker name.
Returns:	return a marker of the following form: `'##--[' + text_marker + ']--##'`
Return type:	str

create_md_file() → mdutils.fileutils.fileutils.MarkDownFile[source]¶: It creates a new Markdown file. :return: return an instance of a MarkDownFile.

get_md_text() → str[source]¶

Instead of writing the markdown text into a file it returns it as a string.

Returns:	return a string with the markdown text.

insert_code(code: str, language: str = '') → str[source]¶

This method allows to insert a peace of code on a markdown file.

Parameters:	code (str) – code string. language (str) – code language: python, c++, c#…
Returns:
Return type:	str

new_checkbox_list(items: List[str], checked: bool = False)[source]¶

Add checkbox list in MarkDown file.

Parameters:	items ([str]) – Array of items for generating the checkbox list. checked (bool) – if you set this to `True`. All checkbox will be checked. By default is `False`.
Returns:

new_header(level: int, title: str, style: str = 'atx', add_table_of_contents: str = 'y', header_id: str = '') → str[source]¶

Add a new header to the Markdown file.

Parameters:

level (int) – Header level. atx style can take values 1 til 6 and setext style take values 1 and 2.
title (str) – Header title.
style (str) – Header style, can be 'atx' or 'setext'. By default 'atx' style is chosen.
add_table_of_contents (str) – by default the atx and setext headers of level 1 and 2 are added to the table of contents, setting this parameter to ‘n’.
header_id (str) – ID of the header for extended Markdown syntax

Example:

>>> from mdutils import MdUtils
>>> mdfile = MdUtils("Header_Example")
>>> print(mdfile.new_header(level=2, title='Header Level 2 Title', style='atx', add_table_of_contents='y'))
'\n## Header Level 2 Title\n'
>>> print(mdfile.new_header(level=2, title='Header Title', style='setext'))
'\nHeader Title\n-------------\n'

static new_inline_image(text: str, path: str) → str[source]¶

Add inline images in a markdown file. For example [MyImage](../MyImage.jpg).

Parameters:	text (str) – Text that is going to be displayed in the markdown file as a iamge. path (str) – Image’s path / link.
Returns:	return the image in markdown format `'![ + text + '](' + path + ')'`.
Return type:	str

new_inline_link(link: str, text: Optional[str] = None, bold_italics_code: str = '', align: str = '') → str[source]¶

Creates a inline link in markdown format.

Parameters:	link (str) – text (str) – Text that is going to be displayed in the markdown file as a link. bold_italics_code (str) – Using `'b'`: bold, `'i'`: italics and `'c'`: `inline_code`… align (str) – Using this parameter you can align text. For example `'right'`, `'left'` or `'center'`.
Returns:	returns the link in markdown format `'[ + text + '](' + link + ')'`. If text is not defined returns `'<' + link + '>'`.
Return type:	str

Note

If param text is not provided, link param will be used instead.

new_line(text: str = '', bold_italics_code: str = '', color: str = 'black', align: str = '', wrap_width: int = 0) → str[source]¶

Add a new line to Markdown file. The text is saved to the global variable file_data_text.

Parameters:	text (str) – is a string containing the paragraph text. Optionally, the paragraph text is returned. bold_italics_code (str) – using `'b'`: bold, `'i'`: italics and `'c'`: `inline_code`… color (str) – Can change text color. For example: `'red'`, `'green'`, `'orange'`… align (str) – Using this parameter you can align text. For example `'right'`, `'left'` or `'center'`. wrap_width (int) – wraps text with designated width by number of characters. By default, long words are not broken. Use width of 0 to disable wrapping.
Returns:	return a string `'\n' + text`. Not necessary to take it, if only has to be written to the file.
Return type:	str

new_list(items: List[str], marked_with: str = '-')[source]¶

Add unordered or ordered list in MarkDown file.

Parameters:	items ([str]) – Array of items for generating the list. marked_with (str) – By default has the value of `'-'`, can be `'+'`, `'*'`. If you want to generate an ordered list then set to `'1'`.
Returns:

new_paragraph(text: str = '', bold_italics_code: str = '', color: str = 'black', align: str = '', wrap_width: int = 0) → str[source]¶

Add a new paragraph to Markdown file. The text is saved to the global variable file_data_text.

Parameters:	text (str) – is a string containing the paragraph text. Optionally, the paragraph text is returned. bold_italics_code (str) – using `'b'`: bold, `'i'`: italics and `'c'`: `inline_code`. color (str) – Can change text color. For example: `'red'`, `'green'`, `'orange'`… align (str) – Using this parameter you can align text. wrap_width (int) – wraps text with designated width by number of characters. By default, long words are not broken. Use width of 0 to disable wrapping.
Returns:	`'\n\n' + text`. Not necessary to take it, if only has to be written to the file.
Return type:	str

new_reference_image(text: str, path: str, reference_tag: Optional[str] = None) → str[source]¶

Add reference images in a markdown file. For example [MyImage][my_image]. All references will be stored at the end of the markdown file.

Parameters:	text (str) – Text that is going to be displayed in the markdown file as a image. path (str) – Image’s path / link. reference_tag (str) – Tag that will be placed at the end of the markdown file jointly with the image’s path.
Returns:	return the image in markdown format `'![ + text + '][' + reference_tag + ']'`.
Return type:	str

Note

If param reference_tag is not provided, text param will be used instead.

new_reference_link(link: str, text: str, reference_tag: Optional[str] = None, bold_italics_code: str = '', align: str = '') → str[source]¶

Creates a reference link in markdown format. All references will be stored at the end of the markdown file.

Parameters:	link (str) – text (str) – Text that is going to be displayed in the markdown file as a link. reference_tag (str) – Tag that will be placed at the end of the markdown file jointly with the link. bold_italics_code (str) – Using `'b'`: bold, `'i'`: italics and `'c'`: `inline_code`… align (str) – Using this parameter you can align text. For example `'right'`, `'left'` or `'center'`.
Returns:	returns the link in markdown format `'[ + text + '][' + link + ]'`.
Return type:	str

Note

If param reference_tag is not provided, text param will be used instead.

Example:

>>> from mdutils import MdUtils
>>> md = MdUtils("Reference link")
>>> link = md.new_reference_link(link='https://github.com', text='github', reference_tag='git')
>>> md.new_link(link)
>>> print(repr(link))
'[github][git]'
>>> link = md.new_reference_link(link='https://github.com/didix21/mdutils', text='mdutils')
>>> md.new_link(link)
>>> print(repr(link))
'[mdutils]'
>>> link = md.new_line(md.new_reference_link(link='https://github.com/didix21/mdutils', text='mdutils', reference_tag='md', bold_italics_code='b'))
>>> md.new_link(link)
>>> print(repr(link))
'[**mdutils**][md]'
>>> md.create_md_file()

new_table(columns: int, rows: int, text: List[str], text_align: str = 'center', marker: str = '') → str[source]¶

This method takes a list of strings and creates a table.

Using arguments columns and rows allows to create a table of n columns and m rows. The columns * rows operations has to correspond to the number of elements of text list argument. Moreover, argument allows to place the table wherever you want from the file.

Parameters:	columns (int) – this variable defines how many columns will have the table. rows (int) – this variable defines how many rows will have the table. text (list) – it is a list containing all the strings which will be placed in the table. text_align (str) – allows to align all the cells to the `'right'`, `'left'` or `'center'`. By default: `'center'`. marker (str) – using `create_marker` method can place the table anywhere of the markdown file.
Returns:	can return the table created as a string.
Return type:	str
Example:

>>> from mdutils import MdUtils
>>> md = MdUtils(file_name='Example')
>>> text_list = ['List of Items', 'Description', 'Result', 'Item 1', 'Description of item 1', '10', 'Item 2', 'Description of item 2', '0']
>>> table = md.new_table(columns=3, rows=3, text=text_list, text_align='center')
>>> print(repr(table))
'\n|List of Items|Description|Result|\n| :---: | :---: | :---: |\n|Item 1|Description of item 1|10|\n|Item 2|Description of item 2|0|\n'

Table result on Markdown¶

List of Items Description Results

Item 1 Description of Item 1 10

Item 2 Description of Item 2 0

new_table_of_contents(table_title: str = 'Table of contents', depth: int = 1, marker: str = '') → str[source]¶

Table of contents can be created if Headers of ‘atx’ style have been defined.

This method allows to create a table of contents and define a title for it. Moreover, depth allows user to define how many levels of headers will be placed in the table of contents. If no marker is defined, the table of contents will be placed automatically after the file’s title.

Parameters:	table_title (str) – The table content’s title, by default “Table of contents” depth (int) – allows to include atx headers 1 through 6. Possible values: 1, 2, 3, 4, 5, or 6. marker (str) – allows to place the table of contents using a marker.
Returns:	a string with the data is returned.
Return type:	str

place_text_using_marker(text: str, marker: str) → str[source]¶

It replace a previous marker created with create_marker with a text string.

This method is going to search for the marker argument, which has been created previously using create_marker method, in file_data_text string.

Parameters:	text (str) – the new string that will replace the marker. marker (str) – the marker that has to be replaced.
Returns:	return a new file_data_text with the replace marker.
Return type:	str

read_md_file(file_name: str) → str[source]¶

Reads a Markdown file and save it to global class file_data_text.

Parameters:	file_name (str) – Markdown file’s name that has to be read.
Returns:	optionally returns the file data content.
Return type:	str

write(text: str = '', bold_italics_code: str = '', color: str = 'black', align: str = '', marker: str = '', wrap_width: int = 0) → str[source]¶

Write text in file_Data_text string.

Parameters:

text (str) – a text a string.
bold_italics_code (str) – using 'b': bold, 'i': italics and 'c': inline_code…
color (str) – Can change text color. For example: 'red', 'green', 'orange'…
align (str) – Using this parameter you can align text. For example 'right', 'left' or 'center'.
wrap_width (int) – wraps text with designated width by number of characters. By default, long words are not broken. Use width of 0 to disable wrapping.
marker (str) – allows to replace a marker on some point of the file by the text.

mdutils package¶

Subpackages¶

Submodules¶

mdutils.mdutils module¶

Module contents¶