pydocmaker 2.2.0__tar.gz → 2.2.2__tar.gz

{pydocmaker-2.2.0/src/pydocmaker.egg-info → pydocmaker-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pydocmaker
-Version: 2.2.0
+Version: 2.2.2
 Summary: a minimal document maker to make docx, markdown, html, textile, redmine, and tex documents from python. Written in pure python.
 Home-page: https://github.com/TobiasGlaubach/pydocmaker
 Author: Tobias Glaubach
@@ -45,7 +45,7 @@ pip install pydocmaker
 
 ## TL;DR;
 
-### Minimal Mini Example:
+### Snippet:
 
 ```python
 
@@ -53,7 +53,6 @@ import pydocmaker as pyd
 
 doc = pyd.Doc.get_example()
 doc.show()
-
 ```
 
 ### Minimal Usage Example:
@@ -70,7 +69,6 @@ doc.add_pre('this will be shown as preformatted') # preformatted
 doc.add_md('This is some *fancy* `markdown` **text**') # markdown
 doc.add_tex(r'\textbf{Hello, LaTeX!}') # latex
 
-
 # this is how to add an image from link
 doc.add_image("https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png", caption='', children='', width=0.8)
 
@@ -132,10 +130,73 @@ import redminelib
 redmine = redminelib.Redmine('https://your-redmine-instance.com', key='your_redmine_token')
 page = doc.to_redmine_upload(redmine, 'your-test-project')
 ```
+### Using Template Folders
+
+pydocmaker supports mounting Jinja2 Templates organized in folders together with (optional) default parameters and assets. Suppose you have the following folder structure 
+
+```
+home/jovyan/templates/
+├─ assets/
+│  ├─ i_can_use_this_everywhere.png
+├─ fancy_tempate.assets/
+│  ├─ fancy_logo.png
+│  ├─ fancy_title_picture.png
+├─ fancy_template.params.json
+├─ fancy_template.tex.j2
+├─ normal_template.params.json
+├─ normal_template.tex.j2
+```
+
+(NOTE: you can also check out the `templates` folder in this repository for an example).
+
+You can then mount this folder in pydocmaker using 
+
+```python
+pyd.register_new_template_dir(r'home/jovyan/templates/')
+```
+
+Which will give you two available templates to use for exporting tex and pdf documents: 
+
+
+```python
+print(pyd.get_available_template_ids())
+```
+`>>> ["fancy_template", "normal_template"]`
+
+
+
+You can mark the templates to be used for a doc by setting it to the reports metadata:
+```python
+import pydocmaker as pyd
+doc = pyd.get_example()
+doc.set_template_to_meta('fancy_template')
+```
+
+which will write all needed data to the documents "metadata". Specifically:
+- `template_id` will hold the id with which the specific template can be loaded. In our case it will be `fancy_template`.
+- `files_to_upload` will hold all assets as base64 encoded bytes in our case the following files:
+   - **key**: `fancy_logo.png` **value** content from `.../fancy_tempate.assets/fancy_logo.png`
+   - **key**: `fancy_title_picture.png` **value** content from `.../fancy_tempate.assets/fancy_title_picture.png` 
+    - **key**: `i_can_use_this_everywhere.png` **value** content from `.../assets/i_can_use_this_everywhere.png` (content from `assets` will be made available shared for all templates)
+- and all other fields loaded from `fancy_template.params.json` will be loaded to the metadata dictionary directly. 
+
+If you thereafter export your document to pdf (or html if you have an html type template), pydocmaker will automatically load the template and render it with parameters, attachments and your document as the body. 
+
+you can view the template and params by 
+```python
+print(doc.get_meta())
+```
+
+and change them by:
+
+```python
+doc.update_meta(author='Me!')
+```
+
 
-### Using Jinja2 Templates for Exporting to HTML or PDF
+### Using Jinja2 Templates Directly for Exporting to HTML or PDF
 
-you can use Jinja2 Templates to make HTML or PDF (latex) documents. An example is given below:
+you can also use Jinja2 Templates directly to make HTML or PDF (latex) documents. An example is given below:
 
 ```python
 

{pydocmaker-2.2.0 → pydocmaker-2.2.2}/README.md

@@ -29,7 +29,7 @@ pip install pydocmaker
 
 ## TL;DR;
 
-### Minimal Mini Example:
+### Snippet:
 
 ```python
 
@@ -37,7 +37,6 @@ import pydocmaker as pyd
 
 doc = pyd.Doc.get_example()
 doc.show()
-
 ```
 
 ### Minimal Usage Example:
@@ -54,7 +53,6 @@ doc.add_pre('this will be shown as preformatted') # preformatted
 doc.add_md('This is some *fancy* `markdown` **text**') # markdown
 doc.add_tex(r'\textbf{Hello, LaTeX!}') # latex
 
-
 # this is how to add an image from link
 doc.add_image("https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png", caption='', children='', width=0.8)
 
@@ -116,10 +114,73 @@ import redminelib
 redmine = redminelib.Redmine('https://your-redmine-instance.com', key='your_redmine_token')
 page = doc.to_redmine_upload(redmine, 'your-test-project')
 ```
+### Using Template Folders
+
+pydocmaker supports mounting Jinja2 Templates organized in folders together with (optional) default parameters and assets. Suppose you have the following folder structure 
+
+```
+home/jovyan/templates/
+├─ assets/
+│  ├─ i_can_use_this_everywhere.png
+├─ fancy_tempate.assets/
+│  ├─ fancy_logo.png
+│  ├─ fancy_title_picture.png
+├─ fancy_template.params.json
+├─ fancy_template.tex.j2
+├─ normal_template.params.json
+├─ normal_template.tex.j2
+```
+
+(NOTE: you can also check out the `templates` folder in this repository for an example).
+
+You can then mount this folder in pydocmaker using 
+
+```python
+pyd.register_new_template_dir(r'home/jovyan/templates/')
+```
+
+Which will give you two available templates to use for exporting tex and pdf documents: 
+
+
+```python
+print(pyd.get_available_template_ids())
+```
+`>>> ["fancy_template", "normal_template"]`
+
+
+
+You can mark the templates to be used for a doc by setting it to the reports metadata:
+```python
+import pydocmaker as pyd
+doc = pyd.get_example()
+doc.set_template_to_meta('fancy_template')
+```
+
+which will write all needed data to the documents "metadata". Specifically:
+- `template_id` will hold the id with which the specific template can be loaded. In our case it will be `fancy_template`.
+- `files_to_upload` will hold all assets as base64 encoded bytes in our case the following files:
+   - **key**: `fancy_logo.png` **value** content from `.../fancy_tempate.assets/fancy_logo.png`
+   - **key**: `fancy_title_picture.png` **value** content from `.../fancy_tempate.assets/fancy_title_picture.png` 
+    - **key**: `i_can_use_this_everywhere.png` **value** content from `.../assets/i_can_use_this_everywhere.png` (content from `assets` will be made available shared for all templates)
+- and all other fields loaded from `fancy_template.params.json` will be loaded to the metadata dictionary directly. 
+
+If you thereafter export your document to pdf (or html if you have an html type template), pydocmaker will automatically load the template and render it with parameters, attachments and your document as the body. 
+
+you can view the template and params by 
+```python
+print(doc.get_meta())
+```
+
+and change them by:
+
+```python
+doc.update_meta(author='Me!')
+```
+
 
-### Using Jinja2 Templates for Exporting to HTML or PDF
+### Using Jinja2 Templates Directly for Exporting to HTML or PDF
 
-you can use Jinja2 Templates to make HTML or PDF (latex) documents. An example is given below:
+you can also use Jinja2 Templates directly to make HTML or PDF (latex) documents. An example is given below:
 
 ```python
 

{pydocmaker-2.2.0 → pydocmaker-2.2.2}/src/pydocmaker/__init__.py

@@ -1,4 +1,4 @@
-__version__ = '2.2.0'
+__version__ = '2.2.2'
 
 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
@@ -8,7 +8,7 @@ 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.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
+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
 

{pydocmaker-2.2.0 → pydocmaker-2.2.2}/src/pydocmaker/backend/ex_tex.py

@@ -115,13 +115,13 @@ def escape(s):
 
 def auto_escape_latex(params):
     if isinstance(params, str):
-        return params if params.startswith('%%latex') else escape(params)
+        return params if params.startswith('%%latex') or params.startswith('%latex') or params.startswith('%tex') else escape(params)
     elif isinstance(params, dict):
         return {k:auto_escape_latex(v) for k, v in params.items()}
     elif isinstance(params, list):
         return [auto_escape_latex(v) for k, v in params.items()]
     else:
-        raise ValueError('Can only auto escape strings, lists, or dicts as parameters!')
+        return params
 
 
 

{pydocmaker-2.2.0 → pydocmaker-2.2.2}/src/pydocmaker/core.py

@@ -51,7 +51,7 @@ def is_notebook() -> bool:
         return False      # Probably standard Python interpreter
 
 
-def show_pdf(pdf_bytes:[bytes|str], width=1000, height=1200):
+def show_pdf(pdf_bytes:bytes, width=1000, height=1200):
     """
     Display a PDF file within an IPython environment.
 

{pydocmaker-2.2.0 → pydocmaker-2.2.2}/src/pydocmaker/templating.py

@@ -28,6 +28,23 @@ def register_new_template_dir(new_template_dir:str, check_exists=True) -> bool:
     registered_template_dirs.add(new_template_dir)
     return new_template_dir in registered_template_dirs
 
+def remove_from_template_dir(to_remove:str) -> bool:
+    """Removes an existing template directory if it exists.
+
+    Args:
+        to_remove (str): The path to remove from the template dirs.
+
+    Returns:
+        bool: Always True
+    """
+
+    global registered_template_dirs
+    if to_remove in registered_template_dirs:
+        registered_template_dirs.remove(to_remove)
+    return True
+
+
+
 def get_registered_template_dirs(include_default=True):
     """Returns a list of registered template directories.
 

{pydocmaker-2.2.0 → pydocmaker-2.2.2/src/pydocmaker.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pydocmaker
-Version: 2.2.0
+Version: 2.2.2
 Summary: a minimal document maker to make docx, markdown, html, textile, redmine, and tex documents from python. Written in pure python.
 Home-page: https://github.com/TobiasGlaubach/pydocmaker
 Author: Tobias Glaubach
@@ -45,7 +45,7 @@ pip install pydocmaker
 
 ## TL;DR;
 
-### Minimal Mini Example:
+### Snippet:
 
 ```python
 
@@ -53,7 +53,6 @@ import pydocmaker as pyd
 
 doc = pyd.Doc.get_example()
 doc.show()
-
 ```
 
 ### Minimal Usage Example:
@@ -70,7 +69,6 @@ doc.add_pre('this will be shown as preformatted') # preformatted
 doc.add_md('This is some *fancy* `markdown` **text**') # markdown
 doc.add_tex(r'\textbf{Hello, LaTeX!}') # latex
 
-
 # this is how to add an image from link
 doc.add_image("https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png", caption='', children='', width=0.8)
 
@@ -132,10 +130,73 @@ import redminelib
 redmine = redminelib.Redmine('https://your-redmine-instance.com', key='your_redmine_token')
 page = doc.to_redmine_upload(redmine, 'your-test-project')
 ```
+### Using Template Folders
+
+pydocmaker supports mounting Jinja2 Templates organized in folders together with (optional) default parameters and assets. Suppose you have the following folder structure 
+
+```
+home/jovyan/templates/
+├─ assets/
+│  ├─ i_can_use_this_everywhere.png
+├─ fancy_tempate.assets/
+│  ├─ fancy_logo.png
+│  ├─ fancy_title_picture.png
+├─ fancy_template.params.json
+├─ fancy_template.tex.j2
+├─ normal_template.params.json
+├─ normal_template.tex.j2
+```
+
+(NOTE: you can also check out the `templates` folder in this repository for an example).
+
+You can then mount this folder in pydocmaker using 
+
+```python
+pyd.register_new_template_dir(r'home/jovyan/templates/')
+```
+
+Which will give you two available templates to use for exporting tex and pdf documents: 
+
+
+```python
+print(pyd.get_available_template_ids())
+```
+`>>> ["fancy_template", "normal_template"]`
+
+
+
+You can mark the templates to be used for a doc by setting it to the reports metadata:
+```python
+import pydocmaker as pyd
+doc = pyd.get_example()
+doc.set_template_to_meta('fancy_template')
+```
+
+which will write all needed data to the documents "metadata". Specifically:
+- `template_id` will hold the id with which the specific template can be loaded. In our case it will be `fancy_template`.
+- `files_to_upload` will hold all assets as base64 encoded bytes in our case the following files:
+   - **key**: `fancy_logo.png` **value** content from `.../fancy_tempate.assets/fancy_logo.png`
+   - **key**: `fancy_title_picture.png` **value** content from `.../fancy_tempate.assets/fancy_title_picture.png` 
+    - **key**: `i_can_use_this_everywhere.png` **value** content from `.../assets/i_can_use_this_everywhere.png` (content from `assets` will be made available shared for all templates)
+- and all other fields loaded from `fancy_template.params.json` will be loaded to the metadata dictionary directly. 
+
+If you thereafter export your document to pdf (or html if you have an html type template), pydocmaker will automatically load the template and render it with parameters, attachments and your document as the body. 
+
+you can view the template and params by 
+```python
+print(doc.get_meta())
+```
+
+and change them by:
+
+```python
+doc.update_meta(author='Me!')
+```
+
 
-### Using Jinja2 Templates for Exporting to HTML or PDF
+### Using Jinja2 Templates Directly for Exporting to HTML or PDF
 
-you can use Jinja2 Templates to make HTML or PDF (latex) documents. An example is given below:
+you can also use Jinja2 Templates directly to make HTML or PDF (latex) documents. An example is given below:
 
 ```python