pydocmaker 2.2.9__py3-none-any.whl

pydocmaker/__init__.py

@@ -0,0 +1,192 @@
+__version__ = '2.2.9'
+
+from pydocmaker.core import DocBuilder, construct, constr, buildingblocks, print_to_pdf, get_latex_compiler, set_latex_compiler, make_pdf_from_tex, show_pdf
+from pydocmaker.util import upload_report_to_redmine, bcolors, txtcolor, colors_dc
+
+
+from pydocmaker.backend.ex_tex import can_run_pandoc
+from pydocmaker.backend.pdf_maker import get_all_installed_latex_compilers, get_latex_compiler
+from pydocmaker.backend.pandoc_api import pandoc_convert_file, pandoc_set_allowed
+
+from pydocmaker.core import DocBuilder as Doc
+from pydocmaker.templating import DocTemplate, TemplateDirSource, register_new_template_dir, get_registered_template_dirs, get_available_template_ids, test_template_exists, remove_from_template_dir
+
+from latex import escape as tex_escape
+
+try:
+    # tests and caches already if pandoc is installed when import is used, so its faster later when we want to use it (or not)
+    can_run_pandoc() 
+except Exception as err:
+    pass
+
+def pandoc_set_enabled():
+    """short for pandoc_set_allowed(True), which will allow pandoc to be used as a valid conversion option"""
+    return pandoc_set_allowed(True)
+
+def pandoc_set_disabled():
+    """short for pandoc_set_allowed(False), which will disallow pandoc to be used as a valid conversion option"""
+    return pandoc_set_allowed(False)
+
+
+def get_schema():
+    return {k: getattr(constr, k)() for k in buildingblocks}
+        
+def get_example():
+    return Doc.get_example()
+
+
+def load(path):
+    """Load a JSON file and return a DocBuilder object.
+
+    Args:
+        path (str or file-like object): The path to the JSON file or a file-like object.
+
+    Returns:
+        DocBuilder: A DocBuilder object initialized with the loaded JSON data.
+
+    Raises:
+        json.JSONDecodeError: If the JSON file is not valid.
+        TypeError: If the loaded JSON object is not of type list.
+    """
+    return DocBuilder.load_json(path)
+
+def md2tex(children='', **kwargs):
+    """convenience function to quickly convert markdown to tex
+
+    Args:
+        children (str, optional): the markdown string to convert. Defaults to ''.
+
+    Returns:
+        str: the corresponding tex string
+    """
+    return Doc().add_md(children=children, **kwargs).to_tex(text_only=True)
+
+
+def mk_chapter(title, description, parent=None, order=None):
+   """Creates a new chapter.
+
+   Args:
+       title (str): The title of the chapter.
+       description (str): A brief description of the chapter.
+       parent (Chapter, optional): The parent chapter. Defaults to None.
+       order (int, optional): The order of the chapter. Defaults to None.
+
+   Returns:
+       Chapter: The newly created chapter.
+   """
+   return DocBuilder.add_chapter(title, description, parent, order)[0]
+
+
+def mk_meta(project_name, version, description, author, author_email, url, license):
+   """
+   Generate metadata for the documentation.
+
+   Args:
+       project_name (str): The name of the project.
+       version (str): The version of the project.
+       description (str): A brief description of the project.
+       author (str): The author's name.
+       author_email (str): The author's email address.
+       url (str): The URL of the project.
+       license (str): The license of the project.
+
+   Returns:
+       dict: A dictionary containing the metadata.
+   """
+   return DocBuilder.add_meta(project_name, version, description, author, author_email, url, license)[0]
+
+
+def mk_tex(children=None, index=None, chapter=None, color='', end=None, **kwargs):
+   """
+   Creates a new LaTeX document part.
+
+   Args:
+       children (str or list, optional): The "children" for this element. Either text directly (as string) or a list of other parts.
+       index (int, optional): The index where to insert the part. If None, appends to the end.
+       chapter (str | int, optional): The chapter name or index where to insert the part. If None, appends to the end.
+       color (str, optional): Any color which can be rendered by HTML or LaTeX. Empty string for default.
+       end (str, optional): If you want to insert a different line ending (than the default) for this element set this argument to any string. None for default.
+       **kwargs: Additional keyword arguments for the document part.
+
+   Returns:
+       dict: The newly created LaTeX document part.
+   """
+   return DocBuilder().add_tex(children=children, index=index, chapter=chapter, color=color, end=end, **kwargs)[0]
+
+def mk_md(children=None, index=None, chapter=None, color='', end=None, **kwargs):
+   """
+   Creates a new markdown document part.
+
+   Args:
+       children (str or list, optional): The "children" for this element. Either text directly (as string) or a list of other parts.
+       index (int, optional): The index where to insert the part. If None, appends to the end.
+       chapter (str | int, optional): The chapter name or index where to insert the part. If None, appends to the end.
+       color (str, optional): Any color which can be rendered by html or latex. Empty string for default.
+       end (str, optional): If you want to insert a different line ending (than the default) for this element set this argument to any string. None for default.
+       **kwargs: Additional keyword arguments for the document part.
+
+   Returns:
+       DocBuilder: A new DocBuilder object with the added markdown document part.
+   """
+   return DocBuilder().add_md(children=children, index=index, chapter=chapter, color=color, end=end, **kwargs)
+
+
+def mk_pre(children=None, index=None, chapter=None, color='', end=None, **kwargs):
+   """
+   Creates a preformatted document part.
+
+   Args:
+       children (str or list, optional): The "children" for this element. Either text directly (as string) or a list of other parts.
+       index (int, optional): The index where to insert the part. If None, appends to the end.
+       chapter (str | int, optional): The chapter name or index where to insert the part. If None, appends to the end.
+       color (str, optional): Any color which can be rendered by HTML or LaTeX. Empty string for default.
+       end (str, optional): If you want to insert a different line ending (than the default) for this element set this argument to any string. None for default.
+       **kwargs: Additional keyword arguments for the document part.
+
+   Returns:
+       dict: The created document part.
+   """
+   return DocBuilder().add_pre(children=children, index=index, chapter=chapter, color=color, end=end, **kwargs)[0]
+
+
+def mk_fig(fig=None, caption='', width=0.8, children=None, color='', end=None, **kwargs):
+    """make an image document part from a pyplot figure type dict from given image input.
+    
+    Args:
+        fig (matplotlib figure, optional): the figure which to upload (or the current figure if None). Defaults to None.
+        caption (str, optional): the caption to give to the image. Defaults to ''.
+        width (float, optional): The width for the image to have in the document. Defaults to 0.8.
+        children (str, optional): A specific name/id to give to the image (will be auto generated if None). Defaults to None.
+        index (int, optional): The index where to insert the part. If None, appends to the end.
+        chapter (str | int, optional): The chapter name or index where to insert the part. If None, appends to the end.
+        color (str, optional): any color which can be rendered by html or latex. Empty string for default.
+        end (str, optional): If you want to insert a different line ending (than the default) for this element set this argument to any string. None for default.
+
+    Returns:
+        dict: The created document part.
+    """
+    return DocBuilder().add_fig(fig=fig, caption=caption, width=width, children=children, color=color, end=end, **kwargs)[0]
+
+def mk_image(image, caption='', width=0.8, children=None, color='', end=None, **kwargs):
+    """make an image type dict from given image input.
+    image can be of type:
+        - pyplot figure
+        - link to download an image from
+        - filelike
+        - numpy NxMx1 or NxMx3 matrix
+        - PIL image
+
+    Args:
+        im (np.array): the image as NxMx
+        caption (str, optional): the caption to give to the image. Defaults to ''.
+        width (float, optional): The width for the image to have in the document. Defaults to 0.8.
+        children (str, optional): A specific name/id to give to the image (will be auto generated if None). Defaults to None.
+        index (int, optional): The index where to insert the part. If None, appends to the end.
+        chapter (str | int, optional): The chapter name or index where to insert the part. If None, appends to the end.
+        color (str, optional): any color which can be rendered by html or latex. Empty string for default.
+        end (str, optional): If you want to insert a different line ending (than the default)  for this element set this argument to any string. None for default.
+
+    """
+    return DocBuilder().add_image(image, caption, width, children, color, end, **kwargs)[0]
+
+

pydocmaker/backend/baseformatter.py

@@ -0,0 +1,173 @@
+import abc
+import traceback
+import os
+
+
+
+from jinja2 import Template
+
+def _handle_template(template, default_template):
+    if template is None:
+        template = default_template
+
+    attachments = {}
+    if hasattr(template, 'render'):
+        template_obj = template
+    elif isinstance(template, str) and os.path.exists(template):
+        with open(template, 'r') as fp:
+            template_obj = Template(fp.read())
+    elif isinstance(template, str) and not template:
+        template_obj = Template('{{ body }}')
+    elif isinstance(template, str):
+        template_obj = Template(template)
+    else:
+        raise KeyError(f'Unknown template type! {type(template)=}')    
+    return template_obj, attachments
+
+
+
+class BaseFormatter(abc.ABC):
+
+    default_linebreak = '\n\n'
+
+    def digest_iterator(self, **kwargs):
+        content = kwargs.get('children', kwargs.get('content'))
+        return f''.join([self.digest(c) for c in content])
+
+    def digest_str(self, el):
+        return str(el)
+
+    def digest_text(self, children='', **kwargs) -> list:
+        return self.digest(children) # will result in digest_str being called
+    
+    def digest_line(self, **kwargs):
+        return self.digest_text(**kwargs) 
+    
+    def digest_meta(self, **kwargs):
+        return '' # meta element will not influence the rendering and is just ignored
+    
+    @abc.abstractmethod
+    def digest_table(self, children=None, **kwargs) -> str:
+        pass
+
+    @abc.abstractmethod
+    def digest_markdown(self, children='', **kwargs) -> str:
+        pass
+
+    @abc.abstractmethod
+    def digest_image(self, children='', width=0.8, caption='', imageblob='', **kwargs) -> str:
+        pass
+
+    @abc.abstractmethod
+    def digest_verbatim(self, children='', **kwargs) -> str:
+        pass
+
+    @abc.abstractmethod
+    def digest_latex(self, children:str, **kwargs):
+        pass
+
+    def digest(self, children, **kwargs) -> str:
+        try:
+            
+            if not children:
+                ret = ''
+            elif isinstance(children, str):
+                ret = self.digest_str(children)
+            elif isinstance(children, dict) and children.get('typ', None) == 'meta':
+                ret = self.digest_meta(children=children, **kwargs)
+            elif isinstance(children, dict) and children.get('typ', None) == 'table':
+                ret = self.digest_table(**children, **kwargs)
+            elif isinstance(children, dict) and children.get('typ', None) == 'iter':
+                ret = self.digest_iterator(children=children, **kwargs)
+            elif isinstance(children, list) and children:
+                ret = self.digest_iterator(children=children, **kwargs)
+            elif isinstance(children, dict) and children.get('typ', None) == 'image':
+                ret = self.digest_image(**children)
+            elif isinstance(children, dict) and children.get('typ', None) == 'text':
+                ret = self.digest_text(**children)
+            elif isinstance(children, dict) and children.get('typ', None) == 'latex':
+                ret = self.digest_latex(**children)
+            elif isinstance(children, dict) and children.get('typ', None) == 'line':
+                ret = self.digest_line(**children)
+            elif isinstance(children, dict) and 'typ' in children and children['typ'] == 'verbatim':
+                ret = self.digest_verbatim(**children)
+            elif isinstance(children, dict) and 'typ' in children and children['typ'] == 'markdown':
+                ret = self.digest_markdown(**children)
+            else:
+                ret = self.handle_error(f'the element of type {type(children)} {children=}, could not be parsed.', children)
+            
+            if isinstance(ret, str):
+                linebreak = self.default_linebreak
+                if isinstance(children, dict):
+                    tmp = children.get('end', None) 
+                    if not tmp is None:
+                        linebreak = tmp
+
+                tmp = kwargs.get('end', None) 
+                if not tmp is None:
+                    linebreak = tmp
+
+                ret += linebreak
+
+            return ret
+        
+        except Exception as err:
+            return self.handle_error(err, children)
+
+
+    def handle_error(self, err, el=None) -> list:
+        e = str(el)
+        if len(e) > 300:
+            e = e[:300] + f'... (n={len(e)-300} more chars hidden)'
+
+        txt = 'ERROR WHILE HANDLING ELEMENT:\n{}\n\n'.format(e)
+        if not isinstance(err, str):
+            txt += '\n'.join(traceback.format_exception(type(err), value=err, tb=err.__traceback__, limit=5))
+        else:
+            txt += err
+        return self.digest_verbatim(children=(txt + '\n'), color='red')
+    
+        
+    def format(self, doc:list) -> str:
+        if hasattr(doc, 'dump'):
+            doc = doc.dump()
+        if not isinstance(doc, list):
+            doc = [doc]
+        return ''.join([self.digest(p) for p in doc])
+    
+
+
+    def _map_table2mat(self, children=None, **kwargs) -> str:
+        if children is None:
+            children = [[]]
+
+        assert isinstance(children, (list, tuple)), f'children must be of type list! but was {type(children)=} {children=}'
+        header = kwargs.get('header', None)
+        header = list(header) if header else []
+
+        assert isinstance(header, (list, tuple)), f'header must be of type list! but was {type(header)=} {header=}'
+        data = list(children)
+        wrong_rows = [row for row in children if not isinstance(row, (list, tuple))]
+        assert not wrong_rows, f'all rows must be of type list! but found {wrong_rows=}'
+
+        n_rows = kwargs.get('n_rows', None)
+        if n_rows is None:
+            n_rows = len(data)
+        n_cols = kwargs.get('n_cols', None)
+        if n_cols is None:
+            n_cols = max(len(header), max([len(row) for row in data]))
+        
+        head = [self.digest(el) for el in header]
+        if len(head) < n_cols:
+            head += ['']*(n_cols-len(head))
+
+        mat = []
+        for i in range(n_rows):
+            mat.append(['']*n_cols)
+
+        for irow, row in enumerate(data):
+            for icol, el in enumerate(row):
+                mat[irow][icol] = self.digest(el)
+
+        return head, mat
+    

pydocmaker/backend/ex_docx.py

@@ -0,0 +1,174 @@
+import traceback
+import io
+
+import base64
+from typing import List
+
+import docx
+from docx.shared import Inches, Pt
+
+import tempfile
+import os
+
+import markdown
+
+try:
+    from pydocmaker.backend.baseformatter import BaseFormatter
+except Exception as err:
+    from .baseformatter import BaseFormatter
+
+can_run_pandoc = lambda : False
+
+
+try:
+    from pydocmaker.backend.pandoc_api import can_run_pandoc, pandoc_convert, pandoc_convert_file
+except Exception as err:
+    from .pandoc_api import can_run_pandoc, pandoc_convert, pandoc_convert_file
+
+try:
+    from pydocmaker.backend.ex_html import convert as convert_html
+except Exception as err:
+    from .ex_html import convert as convert_html
+
+
+
+def blue(run):
+    run.font.color.rgb = docx.shared.RGBColor(0, 0, 255)
+
+def red(run):
+    run.font.color.rgb = docx.shared.RGBColor(255, 0, 0)
+
+def convert_pandoc(doc:List[dict]) -> bytes:
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+        html_file_path = os.path.join(temp_dir, 'temp.html')
+        docx_file_path = os.path.join(temp_dir, 'temp.docx')
+
+        with open(html_file_path, 'w', encoding='utf-8') as fp:
+            fp.write(convert_html(doc))
+        
+        pandoc_convert_file(html_file_path, docx_file_path)
+        with open(docx_file_path, 'rb') as fp:
+            return fp.read()
+        
+def convert(doc:List[dict]) -> bytes:
+
+    if can_run_pandoc():
+        return convert_pandoc(doc)
+    else:
+        renderer = docx_renderer()
+        renderer.digest(doc)
+        return renderer.doc_to_bytes()
+
+class docx_renderer(BaseFormatter):
+    def __init__(self, template_path:str=None, make_blue=False) -> None:
+        self.d = docx.Document(template_path)
+        self.make_blue = make_blue
+
+    def add_paragraph(self, newtext, *args, **kwargs):
+        new_paragraph = self.d.add_paragraph(newtext, *args, **kwargs)
+        if self.make_blue:
+            for r in new_paragraph.runs:
+                blue(r)
+        return new_paragraph
+    
+    def add_run(self, text, *args, **kwargs):
+        if not self.d.paragraphs:
+            self.add_paragraph('')
+
+        last_paragraph = self.d.paragraphs[-1]
+        
+        if not last_paragraph.runs:
+            last_run = last_paragraph.add_run(text)
+        else:
+            last_run = last_paragraph.runs[-1]
+            last_run.add_text(text)
+            
+        if self.make_blue:
+            blue(last_run)
+        return last_run
+        
+    def digest_text(self, children, *args, **kwargs):
+        return self.add_paragraph(children)
+    
+
+    def digest_str(self, children, *args, **kwargs):
+        return self.add_run(children)
+
+    def digest_line(self, children, *args, **kwargs):
+        return self.add_run(children + '\n')
+    
+    def digest_markdown(self, children, *args, **kwargs):
+        return self.add_paragraph(children, style='Normal')
+        
+    def digest_verbatim(self, children, *args, **kwargs):
+        new_run = self.add_run(children)
+        new_run.font.name = 'Courier New'  # Or any other monospace font
+        new_run.font.size = docx.shared.Pt(8)  # Adjust font size as needed
+        return new_run
+
+    def digest_latex(self, children, *args, **kwargs):
+        new_run = self.add_run(children)
+        new_run.font.name = 'Courier New'  # Or any other monospace font
+        new_run.font.size = docx.shared.Pt(8)  # Adjust font size as needed
+        return new_run
+
+
+    def handle_error(self, err, el=None) -> list:
+        if isinstance(err, BaseException):
+            traceback.print_exc(limit=5)
+            err = '\n'.join(traceback.format_exception(type(err), value=err, tb=err.__traceback__, limit=5))
+
+        new_run = self.add_run(err)
+        new_run.font.name = 'Courier New'  # Or any other monospace font
+        new_run.font.size = docx.shared.Pt(8)  # Adjust font size as needed
+        red(new_run)
+        return new_run
+
+
+    def digest_iterator(self, children, *args, **kwargs):
+        if children:
+            return [self.digest(val, *args, **kwargs) for val in children]
+        return []
+
+    def digest_table(self, children=None, **kwargs) -> str:
+        self.handle_error(NotImplementedError(f'exporter of type {type(self)} can not handle tables'))
+    
+    def digest_image(self, children, *args, **kwargs):
+
+        image_width = Inches(max(1, kwargs.get('width', 0.8)*5))
+        image_caption = kwargs.get('caption', '')
+        image_blob = kwargs.get('imageblob', '')
+
+        assert image_blob, 'no image data given!'
+
+        btsb64 = image_blob.split(',')[-1]
+
+        # Decode the base64 image
+        img_bytes = base64.b64decode(btsb64)
+
+        # Create an image stream from the bytes
+        image_stream = io.BytesIO(img_bytes)
+        
+        picture = self.d.add_picture(image_stream, width=image_width)
+        # picture.width = image_width  # Ensure fixed width
+        # picture.height = None  # Adjust height automatically
+        picture.alignment = 1
+
+        run = self.add_paragraph(image_caption)
+        # run.style = 'Caption'  # Apply the 'Caption' style for formatting
+
+        return run
+
+    def format(self, *args, **kwargs):
+        raise NotImplementedError('Can not format a docx document directly')
+    
+
+    def doc_to_bytes(self):
+        with io.BytesIO() as fp:
+            self.d.save(fp)
+            fp.seek(0)
+            return fp.read()
+
+    def save(self, filepath):
+        self.d.save(filepath)