pyMDReport

pyMDReport is a Python package made to automatically create .md reports

Table of contents

• How to install
• Documentation
  • pyMDComponent
    • pyMDComponent.MdRows
    • pyMDComponent.Md
    • pyMDComponent.Fill
  • ComponentData
  • Group
    • Group.Add
    • Group.Fill
  • Text
    • Text.Fill
  • Heading
  • Quote

How To Install

pyMDReport can be installed via pip through

pip install pyMDReport

Documentation

pyMDComponent

Every component in pyMDReport is a child class of pyMDComponent.
pyMDComponents are objects that can be converted in Markdown (md) format.
A pyMDComponent has:

• an identifier ( if not given will use uuid.uuid4() )
• possibly a parent ( a Group, which is also a pyMDComponent )

class pyMDComponent:
    parent: Group | None
    identifier: str             # uuid.uuid4()
    anchor: Anchor | None
    def __init__( self,
            parent: Group | None = None,
            identifier: str | None = None,
            createAnchor: bool = False,
        )

if parent is specified, the component is automatically added to the parent's components dict
Every pyMDComponent has 3 main methods

class pyMDComponent:
    def MdRows( self ) -> list[str]: pass
    def Md( self ) -> str: pass
    def Fill( self, 
        *args: any, 
        **kwargs: any 
    ): pass

• MdRows

  def MdRows(self) -> list[str]

  The MdRows method is responsible of converting the component in a list of .md rows
  Every component has a different MdRows method, since components are converted in md rows in different ways

• Md

  def Md(self) -> str     #'\n'.join(self.MdRows())

  The Md method returns the .md rows in a single string
  By default the rows are joined by newline characters

• Fill

  def Fill( self, 
      *args: any, 
      **kwargs: any 
  ): pass

  The Fill method is responsible of updating the component's data using the params provided
  Every component has a different Fill method, since different components contain different data

ComponentData

class ComponentData:
    args: tuple
    kwargs: dict[str, any]
    def __init__( self,
        *args,
        **kwargs,
    ): pass

CD = ComponentData

ComponentData (alias CD) is just a "storage class" used to group args and kwargs to call a pyMDComponent's Fill method

Group

class Group (pyMDComponent):
    components: dict[str, pyMDComponent]
    def __init__( self, 
        *components: pyMDComponent,
        parent: Group | Report | None = None,
        identifier: str | None = None, 
    ): pass

Child class of pyMDComponent.
A Group is a component that "contains" other components.
Components are associated to their identifier in Group.components
If any pyMDComponent is given on init, the components dict is automatically updated

Group.components = {
    "example" : pyMDComponent,
}

A Group has 2 main methods

class Group (pyMDComponent):
    def Add( self,
        component: pyMDComponent, 
        componentIdentifier : str | None = None, 
    ): pass
    def Fill( self,
        componentData: dict[str, ComponentData], 
    ): pass

• Add

  def Add( self,
      component: pyMDComponent, 
      componentIdentifier : str | None = None, 
  )

  The Add method is responsible of associating the given component to the group.
  It adds the component to Group.components
  If componentIdentifier is specified, it is used as the key associated to the component

- **Fill** ```python def Fill( self, componentData: dict[str, ComponentData], ) ``` The Group's Fill method is responsible of filling each child component with the correspondent data. *componentData* must be a dict associating the child component *identifier* and the [ComponentData](#componentdata) instance

Text

class Text (pyMDComponent):
    text: str
    def __init__( self, 
        text: str | None = None,
    ): pass

Child class of pyMDComponent.
A Text is a basic component that represents text.
If any text is given on init, the components dict is automatically updated
A Text has 1 main method

class Text (pyMDComponent):
    def Fill( self,
        text: str, 
    ): pass

• Fill

  def Fill( self,
      text: str, 
  )

  The Text's Fill method is responsible of storing the given text string.

Heading

class Heading ( Text ):
    MAX_HEADING_LEVEL: int = 3
    def __init__( self,
        headingLevel: int,
    ): pass

Child class of Text.
A Heading is a heading text. headingLevel could be from 1 (highest) to 3 (lowest)
A Heading of level 1 could be created using H1

heading = Heading(1)
# equals
heading = H1()

The same thing can be done with H2 and H3

Quote

class Quote ( Text ):
    pass

Child class of Text.
A Quote is a quoted text.