GH-84: Add types to mdutils methods

mdutils/fileutils/fileutils.py

@@ -5,7 +5,7 @@
 # This file is part of mdutils. https:/didix21/mdutils
 #
 # MIT License: (C) 2018 Dídac Coll
-
+from typing import Optional
 
 class MarkDownFile(object):
  """MarkDownFile class creates a new file of MarkDown extension.
@@ -15,7 +15,7 @@ class MarkDownFile(object):
  - Rewrite a file with new data.
  - Write at the end of the file."""
 
- def __init__(self, name='', dirname: str = None):
+ def __init__(self, name='', dirname: Optional[str] = None):
  """Creates a markdown file, if name is not empty.
  :param str name: provide the file name or a path joinly with the file name. For example: `./my-path/my-file.md`.
  :param str dirname: use dirname if you want to provide the path separately from the name. 
@@ -26,27 +26,27 @@ def __init__(self, name='', dirname: str = None):
  self.file = open(f'{self.file_name}', 'w+', encoding='UTF-8')
  self.file.close()
 
- def _get_file_name(self, name: str, dirname: str = None ) -> str:
+ def _get_file_name(self, name: str, dirname: Optional[str] = None ) -> str:
  if dirname:
  return f'{dirname}/{name}' if name.endswith('.md') else f'{dirname}/{name}.md'
 
  return name if name.endswith('.md') else f'{name}.md'
 
- def rewrite_all_file(self, data):
+ def rewrite_all_file(self, data: str):
  """Rewrite all the data of a Markdown file by ``data``.
 
  :param str data: is a string containing all the data that is written in the markdown file."""
  with open(f'{self.file_name}', 'w', encoding='utf-8') as self.file:
  self.file.write(data)
 
- def append_end(self, data):
+ def append_end(self, data: str):
  """Write at the last position of a Markdown file.
 
  :param str data: is a string containing all the data that is written in the markdown file."""
  with open(f'{self.file_name}', 'a', encoding='utf-8') as self.file:
  self.file.write(data)
 
- def append_after_second_line(self, data):
+ def append_after_second_line(self, data: str):
  """Write after the file's first line.
 
  :param str data: is a string containing all the data that is written in the markdown file."""

mdutils/mdutils.py

@@ -27,6 +27,7 @@
 from mdutils.tools.TextUtils import TextUtils
 from mdutils.tools.MDList import MDList, MDCheckbox
 from textwrap import fill
+from typing import Union, Optional, List
 
 
 class MdUtils:
@@ -44,7 +45,7 @@ class MdUtils:
  - **file_data_text:** contains all the file data that will be written on the markdown file.
  """
 
- def __init__(self, file_name, title="", author=""):
+ def __init__(self, file_name: str, title: str = '', author: str = ''):
  """
 
  :param file_name: it is the name of the Markdown file.
@@ -65,7 +66,7 @@ def __init__(self, file_name, title="", author=""):
  self.reference = Reference()
  self.image = Image(reference=self.reference)
 
- def create_md_file(self):
+ def create_md_file(self) -> MarkDownFile:
  """It creates a new Markdown file.
  :return: return an instance of a MarkDownFile."""
  md_file = MarkDownFile(self.file_name)
@@ -80,7 +81,7 @@ def get_md_text(self) -> str:
  :return: return a string with the markdown text."""
  return self.title + self.table_of_contents + self.file_data_text + self.reference.get_references_as_markdown()
 
- def read_md_file(self, file_name):
+ def read_md_file(self, file_name: str) -> str:
  """Reads a Markdown file and save it to global class `file_data_text`.
 
  :param file_name: Markdown file's name that has to be read.
@@ -93,7 +94,7 @@ def read_md_file(self, file_name):
 
  return file_data
 
- def new_header(self, level, title, style='atx', add_table_of_contents='y', header_id=''):
+ def new_header(self, level: int, title: str, style: str = 'atx', add_table_of_contents: str = 'y', header_id: str = '') -> str:
  """Add a new header to the Markdown file.
 
  :param level: Header level. *atx* style can take values 1 til 6 and *setext* style take values 1 and 2.
@@ -122,7 +123,7 @@ def new_header(self, level, title, style='atx', add_table_of_contents='y', heade
  self.___update_file_data(self.header.choose_header(level, title, style, header_id))
  return self.header.choose_header(level, title, style, header_id)
 
- def __add_new_item_table_of_content(self, level, item):
+ def __add_new_item_table_of_content(self, level: int, item: Union[List[str], str]):
  """Automatically add new atx headers to the table of contents.
 
  :param level: add levels up to 6.
@@ -143,7 +144,7 @@ def __add_new_item_table_of_content(self, level, item):
  curr.append([])
 
 
- def new_table_of_contents(self, table_title="Table of contents", depth=1, marker=''):
+ def new_table_of_contents(self, table_title: str = "Table of contents", depth: int = 1, marker: str = '') -> str:
  """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
@@ -175,7 +176,7 @@ def new_table_of_contents(self, table_title="Table of contents", depth=1, marker
 
  return self.table_of_contents + marker_table_of_contents
 
- def new_table(self, columns, rows, text, text_align='center', marker=''):
+ def new_table(self, columns: int, rows: int, text: List[str], text_align: str = 'center', marker: str = '') -> str:
  """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
@@ -222,7 +223,7 @@ def new_table(self, columns, rows, text, text_align='center', marker=''):
 
  return text_table
 
- def new_paragraph(self, text='', bold_italics_code='', color='black', align='', wrap_width=0):
+ def new_paragraph(self, text: str = '', bold_italics_code: str = '', color: str = 'black', align: str = '', wrap_width:int = 0) -> str:
  """Add a new paragraph to Markdown file. The text is saved to the global variable file_data_text.
 
  :param text: is a string containing the paragraph text. Optionally, the paragraph text is returned.
@@ -252,7 +253,7 @@ def new_paragraph(self, text='', bold_italics_code='', color='black', align='',
 
  return self.file_data_text
 
- def new_line(self, text='', bold_italics_code='', color='black', align='', wrap_width=0):
+ def new_line(self, text: str = '', bold_italics_code: str = '', color: str = 'black', align: str = '', wrap_width: int = 0) -> str:
  """Add a new line to Markdown file. The text is saved to the global variable file_data_text.
 
  :param text: is a string containing the paragraph text. Optionally, the paragraph text is returned.
@@ -281,7 +282,7 @@ def new_line(self, text='', bold_italics_code='', color='black', align='', wrap_
 
  return self.file_data_text
 
- def write(self, text='', bold_italics_code='', color='black', align='', marker='', wrap_width=0):
+ def write(self, text: str = '', bold_italics_code: str = '', color: str = 'black', align: str = '', marker: str = '', wrap_width: int = 0) -> str:
  """Write text in ``file_Data_text`` string.
 
  :param text: a text a string.
@@ -314,7 +315,7 @@ def write(self, text='', bold_italics_code='', color='black', align='', marker='
 
  return new_text
 
- def insert_code(self, code, language=''):
+ def insert_code(self, code: str, language: str = '') -> str:
  """This method allows to insert a peace of code on a markdown file.
 
  :param code: code string.
@@ -328,7 +329,7 @@ def insert_code(self, code, language=''):
  self.___update_file_data(md_code)
  return md_code
 
- def create_marker(self, text_marker):
+ def create_marker(self, text_marker: str) -> str:
  """This will add a marker to ``file_data_text`` and returns the marker result in order to be used whenever
  you need.
 
@@ -345,7 +346,7 @@ def create_marker(self, text_marker):
  self.___update_file_data(new_marker)
  return new_marker
 
- def place_text_using_marker(self, text, marker):
+ def place_text_using_marker(self, text: str, marker: str) -> str:
  """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
@@ -363,7 +364,7 @@ def place_text_using_marker(self, text, marker):
  def ___update_file_data(self, file_data):
  self.file_data_text += file_data
 
- def new_inline_link(self, link, text=None, bold_italics_code='', align=''):
+ def new_inline_link(self, link: str, text: Optional[str] = None, bold_italics_code: str = '', align: str = '') -> str:
  """Creates a inline link in markdown format.
 
  :param link:
@@ -392,7 +393,7 @@ def new_inline_link(self, link, text=None, bold_italics_code='', align=''):
 
  return Inline.new_link(link=link, text=n_text)
 
- def new_reference_link(self, link, text, reference_tag=None, bold_italics_code='', align=''):
+ def new_reference_link(self, link: str, text: str, reference_tag: Optional[str] = None, bold_italics_code: str = '', align: str = '') -> str:
  """Creates a reference link in markdown format. All references will be stored at the end of the markdown file.
 
 
@@ -444,7 +445,7 @@ def new_reference_link(self, link, text, reference_tag=None, bold_italics_code='
  return self.reference.new_link(link=link, text=n_text, reference_tag=reference_tag)
 
  @staticmethod
- def new_inline_image(text, path):
+ def new_inline_image(text: str, path: str) -> str:
  """Add inline images in a markdown file. For example ``[MyImage](../MyImage.jpg)``.
 
  :param text: Text that is going to be displayed in the markdown file as a iamge.
@@ -458,7 +459,7 @@ def new_inline_image(text, path):
 
  return Image.new_inline_image(text=text, path=path)
 
- def new_reference_image(self, text, path, reference_tag=None):
+ def new_reference_image(self, text: str, path: str, reference_tag: Optional[str] = None) -> str:
  """Add reference images in a markdown file. For example ``[MyImage][my_image]``. All references will be stored
  at the end of the markdown file.
 
@@ -476,7 +477,7 @@ def new_reference_image(self, text, path, reference_tag=None):
  """
  return self.image.new_reference_image(text=text, path=path, reference_tag=reference_tag)
 
- def new_list(self, items: [str], marked_with: str = "-"):
+ def new_list(self, items: List[str], marked_with: str = "-"):
  """Add unordered or ordered list in MarkDown file.
 
  :param items: Array of items for generating the list.
@@ -489,7 +490,7 @@ def new_list(self, items: [str], marked_with: str = "-"):
  mdlist = MDList(items, marked_with)
  self.___update_file_data('\n' + mdlist.get_md())
 
- def new_checkbox_list(self, items: [str], checked: bool = False):
+ def new_checkbox_list(self, items: List[str], checked: bool = False):
  """Add checkbox list in MarkDown file.
 
  :param items: Array of items for generating the checkbox list.

mdutils/tools/Header.py

@@ -25,7 +25,7 @@ class Header:
  # * Atx-Style *
  # ********************************************************************
  @staticmethod
- def atx_level_1(title, header_id=''):
+ def atx_level_1(title: str, header_id: str = '') -> str:
  """Return a atx level 1 header.
 
  :param str title: text title.
@@ -39,7 +39,7 @@ def atx_level_1(title, header_id=''):
  return '\n# ' + title + header_id + '\n'
 
  @staticmethod
- def atx_level_2(title, header_id=''):
+ def atx_level_2(title: str, header_id: str = '') -> str:
  """Return a atx level 2 header.
 
  :param str title: text title.
@@ -53,7 +53,7 @@ def atx_level_2(title, header_id=''):
  return '\n## ' + title + header_id + '\n'
 
  @staticmethod
- def atx_level_3(title, header_id=''):
+ def atx_level_3(title: str, header_id: str = '') -> str:
  """Return a atx level 3 header.
 
  :param str title: text title.
@@ -67,7 +67,7 @@ def atx_level_3(title, header_id=''):
  return '\n### ' + title + header_id + '\n'
 
  @staticmethod
- def atx_level_4(title, header_id=''):
+ def atx_level_4(title: str, header_id: str = '') -> str:
  """Return a atx level 4 header.
 
  :param str title: text title.
@@ -81,7 +81,7 @@ def atx_level_4(title, header_id=''):
  return '\n#### ' + title + header_id + '\n'
 
  @staticmethod
- def atx_level_5(title, header_id=''):
+ def atx_level_5(title: str, header_id: str = '') -> str:
  """Return a atx level 5 header.
 
  :param str title: text title.
@@ -95,7 +95,7 @@ def atx_level_5(title, header_id=''):
  return '\n##### ' + title + header_id + '\n'
 
  @staticmethod
- def atx_level_6(title, header_id=''):
+ def atx_level_6(title: str, header_id: str = '') -> str:
  """Return a atx level 6 header.
 
  :param str title: text title.
@@ -112,7 +112,7 @@ def atx_level_6(title, header_id=''):
  # * Setext-Style *
  # ********************************************************************
  @staticmethod
- def setext_level_1(title):
+ def setext_level_1(title: str) -> str:
  """Return a setext level 1 header.
 
  :param str title: text title.
@@ -123,7 +123,7 @@ def setext_level_1(title):
  return '\n' + title + '\n' + ''.join(['=' for _ in title]) + '\n'
 
  @staticmethod
- def setext_level_2(title):
+ def setext_level_2(title: str) -> str:
  """Return a setext level 1 header.
 
  :param str title: text title.
@@ -134,7 +134,7 @@ def setext_level_2(title):
  return '\n' + title + '\n' + ''.join(['-' for _ in title]) + '\n'
 
  @staticmethod
- def header_anchor(text, link=""):
+ def header_anchor(text: str, link: str = '') -> str:
  """Creates an internal link of a defined Header level 1 or level 2 in the markdown file.
 
  Giving a text string an text link you can create an internal link of already existing header. If the ``link``
@@ -160,7 +160,7 @@ def header_anchor(text, link=""):
  return '[' + text + '](' + link + ')'
 
  @staticmethod
- def choose_header(level, title, style='atx', header_id=''):
+ def choose_header(level: int, title: str, style: str = 'atx', header_id: str = '') -> str:
  # noinspection SpellCheckingInspection
  """This method choose the style and the header level.
 

mdutils/tools/Image.py

@@ -11,15 +11,15 @@
 
 class Image:
 
- def __init__(self, reference):
+ def __init__(self, reference: Reference):
  """
  :param reference:
  :type reference: Reference
  """
  self.reference = reference
 
  @staticmethod
- def new_inline_image(text, path, tooltip=None):
+ def new_inline_image(text: str, path: str, tooltip: str = None) -> str:
  """
  :param text: Text that is going to be displayed in the markdown file as a iamge.
  :type text: str
@@ -32,7 +32,7 @@ def new_inline_image(text, path, tooltip=None):
  """
  return '!' + Inline.new_link(link=path, text=text, tooltip=tooltip)
 
- def new_reference_image(self, text, path, reference_tag=None, tooltip=None):
+ def new_reference_image(self, text: str, path: str, reference_tag: str = None, tooltip: str = None) -> str:
  """
  :param text: Text that is going to be displayed in the markdown file as a image.
  :type text: str