mdutils package

Subpackages

• mdutils.fileutils package
  • Submodules
  • mdutils.fileutils.fileutils module
  • Module contents
• mdutils.tools package
  • Submodules
  • mdutils.tools.tools module
  • Module contents

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, title='', author='')

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)

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()

It creates a new Markdown file. :return: return an instance of a MarkDownFile.

insert_code(code, language='')

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_header(level, title, style='atx', add_table_of_contents='y')

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’.

The example below consist in creating two types Headers examples:

Example:

>>> 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'

new_line(text='', bold_italics_code='', color='black', align='')

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) – bold_italics_code: 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.

Returns:

return a string '\n' + text. Not necessary to take it, if only has to be written to the file.

Return type:

str

new_paragraph(text='', bold_italics_code='', color='black', align='')

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) – bold_italics_code: 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.

Returns:

'\n\n' + text. Not necessary to take it, if only has to be written to the file.

Return type:

str

new_table(columns, rows, text, text_align='center', marker='')

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.tools.tools import Table
>>> text_list = ['List of Items', 'Description', 'Result', 'Item 1', 'Description of item 1', '10', 'Item 2', 'Description of item 2', '0']
>>> table = Table().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='Table of contents', depth=1, marker='')

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 if headers of level 1 and 2 or only level 1 have to be placed on 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 Headers 1 and 2 or only Headers of level 1. Possible values 1 or 2.
• 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, marker)

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)

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='', bold_italics_code='', color='black', align='', marker='')

Write text in file_Data_text string.

Parameters:

• text (str) – a text a string.
• bold_italics_code (str) – bold_italics_code: 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.
• marker (str) – allows to replace a marker on some point of the file by the text.

Module contents