Metadata-Version: 2.4
Name: docx_renderer
Version: 0.2.0
Summary: Render ppt like a jupyter notebook
Author-email: Najeem Muhammed <najeem@gmail.com>
License: MIT License
        
        Copyright (c) 2023, Najeem Muhammed
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/idling-mind/docx_renderer
Project-URL: Bug Tracker, https://github.com/idling-mind/docx_renderer/issues
Keywords: microsoft,word,doc,docx,document,pages,report
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-docx>=1.1.0
Requires-Dist: click
Requires-Dist: Pillow>=9.3
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: coverage; extra == "test"
Dynamic: license-file

# DOCX Renderer

This package lets you run your Microsoft Word documents like a script.
You can insert placeholders in the document and use either a Python function
or an equivalent command-line tool to convert it into an output rendered document.

[Documentation](https://docx-renderer.readthedocs.io/en)

## Installation
```console
pip install docx-renderer
```

## Usage
Below is a simple example.

```python
from docx_renderer import DOCXRenderer
p = DOCXRenderer("template.docx")

someval = "world!"
def mymethod(abc):
    return f"{abc} " * 5

p.render(
    "output.docx", 
    {
        "variable": someval, "mymethod": mymethod, "myimage": "is_it_worth.png"
    }
)
```

This will replace placeholders in the template document with the provided values.

## Before

![Before](./docs/_src/_static/before.png)

## After

![After](./docs/_src/_static/after.png)

You can define some functions within the document itself by writing Python code in
the comments section. The variables and functions in this code can be used in the main document.

For example: write the following in one of the comments in the document.

<pre>
```python
def myfunc(input):
    return input * 42
```
</pre>

Now you can, for example, add the placeholder `{{{myfunc(42)}}}` in your document.

If the template document is a self-contained Python script (i.e., it does not require
variable values and function definitions to be passed from outside), you can
generate the output document directly from the command line using the following
command.

```console
docx-renderer input_template.docx output_file.docx
```

## Placeholders
You can have placeholders for text, images, or tables. Placeholders can be added
as regular text. All placeholders should be enclosed within a pair
of triple braces (`{{{` and `}}}`).

### Text
Any placeholder which can be evaluated into a string can act as a text placeholder.

For example: `{{{"hello " * 10/2}}}` or `{{{abs(-2)}}}`

### Image
If you have added `:image()` as a suffix to the Python statement, the renderer will
try to convert the value of the Python statement to a file location and insert an
image from that file location.

For example: `{{{"c:\\temp\\myimage.png":image()}}}`

### Table
Tables are similar to images, but instead of a string, the Python
statement should evaluate to a list of lists. Then you can add `:table()` as a
suffix, and it will be converted to a table inside the document.

For example: `{{{[["col1", "col2", "col3"],[1, 2, 3]]:table()}}}` will render to

|col1 | col2 | col3|
|-----|------|-----|
|1    |2     |3    |
