MODULE

MKAPI.CORE.BASE

This module provides entity classes to represent docstring structure.

Classes
dataclass

mkapi.core.base.Base(name='', markdown='')

Base class.

Parameters
  • name (str, optional) Name of self.
  • markdown (str, optional) Markdown source.
Attributes
  • callback (callable(Base: str), optional) Callback function to modify HTML output.
  • html (str) HTML output after conversion.
  • markdown (str) Markdown source.
  • name (str) Name of self.
Examples
>>> base = Base('x', 'markdown')
>>> base
Base('x')
>>> bool(base)
True
>>> list(base)
[Base('x')]
>>> base = Base()
>>> bool(base)
False
>>> list(base)
[]
Methods
method

__bool__() → bool

Returns True if name is not empty.

generator

__iter__()Base

Yields self if markdown is not empty.

method

set_html(html)

Sets HTML output.

Parameters
  • html (str) HTML output.
method

copy()

Returns a copy of the Base instance.

dataclass

mkapi.core.base.Inline(name='')

Inline class.

Parameters
  • name (str, optional) Name of self.
Attributes
  • callback (callable(Base: str), optional) Callback function to modify HTML output.
  • html (str) HTML output after conversion.
  • markdown (str) Markdown source.
  • name (str) Name of self.
Examples
>>> inline = Inline()
>>> bool(inline)
False
>>> inline = Inline('markdown')
>>> inline.name == inline.markdown
True
>>> inline
Inline('markdown')
>>> bool(inline)
True
>>> next(iter(inline)) is inline
True
>>> inline.set_html("<p>p1</p><p>p2</p>")
>>> inline.html
'p1<br>p2'
>>> inline.copy()
Inline('markdown')
Methods
  • __bool__() (bool) Returns True if name is not empty.</>
  • __iter__() (Base) Yields self if markdown is not empty.</>
  • copy() Returns a copy of the Inline instance.</>
  • set_html(html) Sets html attribute cleaning p tags.</>
method

__bool__() → bool

Returns True if name is not empty.

generator

__iter__()Base

Yields self if markdown is not empty.

method

set_html(html)

Sets html attribute cleaning p tags.

Parameters
  • html (str) HTML output.
method

copy()

Returns a copy of the Inline instance.

dataclass

mkapi.core.base.Type(name='')

Type class represents type of Item, Section, Docstring, or Object.

Parameters
  • name (str, optional) Name of self.
Attributes
  • callback (callable(Base: str), optional) Callback function to modify HTML output.
  • html (str) HTML output after conversion.
  • markdown (str) Markdown source.
  • name (str) Name of self.
Examples
>>> a = Type('str')
>>> a
Type('str')
>>> list(a)
[]
>>> b = Type('[Object](base.Object)')
>>> b.markdown
'[Object](base.Object)'
>>> list(b)
[Type('[Object](base.Object)')]
>>> a.copy()
Type('str')
Methods
  • __bool__() (bool) Returns True if name is not empty.</>
  • __iter__() (Base) Yields self if markdown is not empty.</>
  • copy() Returns a copy of the Type instance.</>
  • set_html(html) Sets html attribute cleaning p tags.</>
method

__bool__() → bool

Returns True if name is not empty.

generator

__iter__()Base

Yields self if markdown is not empty.

method

set_html(html)

Sets html attribute cleaning p tags.

Parameters
  • html (str) HTML output.
method

copy()

Returns a copy of the Type instance.

dataclass

mkapi.core.base.Item(name='', type=<factory>, description=<factory>, kind='')

Item class represents an item in Parameters, Attributes, and Raises sections, etc.

Parameters
  • name (str, optional) Name of self.
  • type (Type, optional) Type of self.
  • description (Inline, optional) Description of self.
  • kind (str, optional) Kind of self, for example readonly property. This value is rendered as a class attribute in HTML.
Attributes
  • callback (callable(Base: str), optional) Callback function to modify HTML output.
  • description (Inline) Description of self.
  • html (str) HTML output after conversion.
  • kind (str) Kind of self, for example readonly property. This value is rendered as a class attribute in HTML.
  • markdown (str) Markdown source.
  • name (str) Name of self.
  • type (Type) Type of self.
Examples
>>> item = Item('[x](x)', Type('int'), Inline('A parameter.'))
>>> item
Item('[x](x)', 'int')
>>> item.name, item.markdown, item.html
('[x](x)', '[x](x)', '')
>>> item.type
Type('int')
>>> item.description
Inline('A parameter.')
>>> item = Item('[x](x)', 'str', 'A parameter.')
>>> item.type
Type('str')
>>> it = iter(item)
>>> next(it) is item
True
>>> next(it) is item.description
True
>>> item.set_html('<p><strong>init</strong></p>')
>>> item.html
'__init__'
Methods
  • __bool__() (bool) Returns True if name is not empty.</>
  • __iter__() (Base) Yields self if markdown is not empty.</>
  • copy() Returns a copy of the Item instance.</>
  • set_description(description, force) Sets description.</>
  • set_html(html) Sets html attribute cleaning p tags.</>
  • set_type(type, force) Sets type.</>
  • to_tuple() (str, str, str) Returns a tuple of (name, type, description).</>
  • update(item, force) Updates type and description.</>
method

__bool__() → bool

Returns True if name is not empty.

generator

__iter__()Base

Yields self if markdown is not empty.

method

set_html(html)

Sets html attribute cleaning p tags.

Parameters
  • html (str) HTML output.
method

to_tuple() → (str, str, str)

Returns a tuple of (name, type, description).

Examples
>>> item = Item('[x](x)', 'int', 'A parameter.')
>>> item.to_tuple()
('[x](x)', 'int', 'A parameter.')
method

set_type(type, force=False)

Sets type.

Parameters
  • type (Type)
  • force (bool, optional) If True, overwrite self regardless of existing type and description.
  • item Type instance.
See Also
method

set_description(description, force=False)

Sets description.

Parameters
  • description (Inline) Inline instance.
  • force (bool, optional) If True, overwrite self regardless of existing type and description.
See Also
method

update(item, force=False)

Updates type and description.

Parameters
  • item (Item) Item instance.
  • force (bool, optional) If True, overwrite self regardless of existing type and description.
Examples
>>> item = Item('x')
>>> item2 = Item('x', 'int', 'description')
>>> item.update(item2)
>>> item.to_tuple()
('x', 'int', 'description')
>>> item2 = Item('x', 'str', 'new description')
>>> item.update(item2)
>>> item.to_tuple()
('x', 'int', 'description')
>>> item.update(item2, force=True)
>>> item.to_tuple()
('x', 'str', 'new description')
>>> item.update(Item('x'), force=True)
>>> item.to_tuple()
('x', 'str', 'new description')
method

copy()

Returns a copy of the Item instance.

dataclass

mkapi.core.base.Section(name='', markdown='', items=<factory>, type=<factory>)

Section class represents a section in docstring.

Parameters
  • name (str, optional) Name of self.
  • markdown (str, optional) Markdown source.
  • items (list of Item, optional) List for Arguments, Attributes, or Raises sections, etc.
  • type (Type, optional) Type of self.
Attributes
  • callback (callable(Base: str), optional) Callback function to modify HTML output.
  • html (str) HTML output after conversion.
  • items (list of Item) List for Arguments, Attributes, or Raises sections, etc.
  • markdown (str) Markdown source.
  • name (str) Name of self.
  • type (Type) Type of self.
Examples
>>> items = [Item('x'), Item('[y](a)'), Item('z')]
>>> section = Section('Parameters', items=items)
>>> section
Section('Parameters', num_items=3)
>>> list(section)
[Item('[y](a)', '')]
Methods
method

set_html(html)

Sets HTML output.

Parameters
  • html (str) HTML output.
method

__bool__()

Returns True if the number of items is larger than 0.

generator

__iter__()Base

Yields a Base instance that has non empty Markdown.

method

__getitem__(name)Item

Returns an Item instance whose name is equal to name.

If there is no Item instance, a Item instance is newly created.

Parameters
  • name (str) Item name.
Examples
>>> section = Section("", items=[Item('x')])
>>> section['x']
Item('x', '')
>>> section['y']
Item('y', '')
>>> section.items
[Item('x', ''), Item('y', '')]
method

__delitem__(name)

Delete an Item instance whose name is equal to name.

Parameters
  • name (str) Item name.
method

__contains__(name) → bool

Returns True if there is an Item instance whose name is equal to name.

Parameters
  • name (str) Item name.
method

set_item(item, force=False)

Sets an Item.

Parameters
  • item (Item) Item instance.
  • force (bool, optional) If True, overwrite self regardless of existing item.
Examples
>>> items = [Item('x', 'int'), Item('y', 'str', 'y')]
>>> section = Section('Parameters', items=items)
>>> section.set_item(Item('x', 'float', 'X'))
>>> section['x'].to_tuple()
('x', 'int', 'X')
>>> section.set_item(Item('y', 'int', 'Y'), force=True)
>>> section['y'].to_tuple()
('y', 'int', 'Y')
>>> section.set_item(Item('z', 'float', 'Z'))
>>> [item.name for item in section.items]
['x', 'y', 'z']
See Also
method

update(section, force=False)

Updates items.

Parameters
  • section (Section) Section instance.
  • force (bool, optional) If True, overwrite items of self regardless of existing value.
Examples
>>> s1 = Section('Parameters', items=[Item('a', 's'), Item('b', 'f')])
>>> s2 = Section('Parameters', items=[Item('a', 'i', 'A'), Item('x', 'd')])
>>> s1.update(s2)
>>> s1['a'].to_tuple()
('a', 's', 'A')
>>> s1['x'].to_tuple()
('x', 'd', '')
>>> s1.update(s2, force=True)
>>> s1['a'].to_tuple()
('a', 'i', 'A')
>>> s1.items
[Item('a', 'i'), Item('b', 'f'), Item('x', 'd')]
method

merge(section, force=False)Section

Returns a merged Section

Parameters
  • section (Section)
  • force (bool, optional)
Examples
>>> s1 = Section('Parameters', items=[Item('a', 's'), Item('b', 'f')])
>>> s2 = Section('Parameters', items=[Item('a', 'i'), Item('c', 'd')])
>>> s3 = s1.merge(s2)
>>> s3.items
[Item('a', 's'), Item('b', 'f'), Item('c', 'd')]
>>> s3 = s1.merge(s2, force=True)
>>> s3.items
[Item('a', 'i'), Item('b', 'f'), Item('c', 'd')]
>>> s3 = s2.merge(s1)
>>> s3.items
[Item('a', 'i'), Item('c', 'd'), Item('b', 'f')]
method

copy()

Returns a copy of the Section instace.

Examples
>>> s = Section('E', 'markdown', [Item('a', 's'), Item('b', 'i')])
>>> s.copy()
Section('E', num_items=2)
dataclass

mkapi.core.base.Docstring(sections=<factory>, type=<factory>)

Docstring class represents a docstring of an object.

Parameters
  • sections (list of Section, optional) List of Section instance.
  • type (Type, optional) Type for Returns or Yields sections.
Attributes
  • sections (list of Section) List of Section instance.
  • type (Type) Type for Returns or Yields sections.
Examples

Empty docstring:

>>> docstring = Docstring()
>>> assert not docstring

Docstring with 3 sections:

>>> default = Section("", markdown="Default")
>>> parameters = Section("Parameters", items=[Item("a"), Item("[b](!a)")])
>>> returns = Section("Returns", markdown="Results")
>>> docstring = Docstring([default, parameters, returns])
>>> docstring
Docstring(num_sections=3)

Docstring is iterable:

>>> list(docstring)
[Section('', num_items=0), Item('[b](!a)', ''), Section('Returns', num_items=0)]

Indexing:

>>> docstring["Parameters"].items[0].name
'a'

Section ordering:

>>> docstring = Docstring()
>>> _ = docstring['']
>>> _ = docstring['Todo']
>>> _ = docstring['Attributes']
>>> _ = docstring['Parameters']
>>> [section.name for section in docstring.sections]
['', 'Parameters', 'Attributes', 'Todo']
Methods
method

__bool__()

Returns True if the number of sections is larger than 0.

generator

__iter__()Base

Yields Base instance.

method

__getitem__(name)Section

Returns a Section instance whose name is equal to name.

If there is no Section instance, a Section instance is newly created.

Parameters
  • name (str) Section name.
method

__contains__(name) → bool

Returns True if there is a Section instance whose name is equal to name.

Parameters
  • name Section name.
method

set_section(section, force=False, copy=False, replace=False)

Sets a Section.

Parameters
  • section (Section) Section instance.
  • force (bool, optional) If True, overwrite self regardless of existing seciton.
  • copy (bool, optional)
  • replace (bool, optional)
Examples
>>> items = [Item('x', 'int'), Item('y', 'str', 'y')]
>>> s1 = Section('Attributes', items=items)
>>> items = [Item('x', 'str', 'X'), Item('z', 'str', 'z')]
>>> s2 = Section('Attributes', items=items)
>>> doc = Docstring([s1])
>>> doc.set_section(s2)
>>> doc['Attributes']['x'].to_tuple()
('x', 'int', 'X')
>>> doc['Attributes']['z'].to_tuple()
('z', 'str', 'z')
>>> doc.set_section(s2, force=True)
>>> doc['Attributes']['x'].to_tuple()
('x', 'str', 'X')
>>> items = [Item('x', 'X', 'str'), Item('z', 'z', 'str')]
>>> s3 = Section('Parameters', items=items)
>>> doc.set_section(s3)
>>> doc.sections
[Section('Parameters', num_items=2), Section('Attributes', num_items=3)]