pandadoc 0.1.0

Description:

pandadoc 0.1.0

pandadoc: lightweight pandoc wrapper






An extremely lightweight pandoc wrapper for Python 3.8+.
Its features:

Supports conversion between all formats that pandoc supports -
markdown, HTML, LaTeX, Word, epub, pdf (output),
and more.
Output to raw bytes (binary formats - e.g. PDF), to str objects
(text formats - e.g. markdown), or to file (any format).
pandoc errors are raised as (informative) exceptions.
Full flexibility of the pandoc command-line tool, and the same syntax. (See the
pandoc manual for more information.)


Getting Started Guide

Installation
First, ensure pandoc is on your PATH.
(In other words, install pandoc and add it to
your PATH.)
Then install pandadoc from PyPI:
$ python -m pip install pandadoc
That’s it.


Usage
Convert a webpage to markdown, and store it as a python str:
>>> import pandadoc
>>> input_url = "https://example.com/"
>>> example_md = pandadoc.call_pandoc(
... options=["-t", "markdown"], files=[input_url]
... )
>>> print(example_md)
<div>

# Example Domain

This domain is for use in illustrative examples in documents.
...
Now convert the markdown to RTF, and write it to a file:
>>> rtf_output_file = "example.rtf"
>>> pandadoc.call_pandoc(
... options=["-f", "markdown", "-t", "rtf", "-o", rtf_output_file],
... input_text=example_md,
... )
''
Notice that call_pandoc returns an empty string '' when a file output is used.
Looking at the output file:
{\pard \ql \f0 \sa180 \li0 \fi0 \outlinelevel0 \b \fs36 Example Domain\par}
{\pard \ql \f0 \sa180 \li0 \fi0 This domain is for use in illustrative examples in documents. You may use this domain in literature without prior coordination or asking for permission.\par}
{\pard \ql \f0 \sa180 \li0 \fi0 {\field{\*\fldinst{HYPERLINK "https://www.iana.org/domains/example"}}{\fldrslt{\ul
More information...
}}}
\par}
Convert this RTF document to PDF, using xelatex with a custom character set,
and store the result as raw bytes:
>>> raw_pdf = pandadoc.call_pandoc(
... options=["-f", "markdown", "-t", "pdf", "--pdf-engine", "xelatex", "--variable-mainfont", "Palatino"],
... files=[rtf_output_file],
... decode=False,
... )
Note that PDF conversion requires a
“PDF engine”
(e.g. pdflatex, latexmk etc.) to be installed.
Now you can send those raw bytes over a network, or write them to a file:
>>> with open("example.pdf", "wb") as f:
... f.write(raw_pdf)
...
>>> # Finished
You can find more pandoc examples here.


Exceptions
If pandoc exits with an error, an appropriate exception is raised (based on the
exit code):
>>> pandadoc.call_pandoc(
... options=["-f", "markdown", "-t", "zzz"], # non-existent format
... input_text=example_md,
... )
Traceback (most recent call last):
...
pandadoc.exceptions.PandocUnknownWriterError: Unknown output format zzz
>>> isinstance(pandadoc.exceptions.PandocUnknownWriterError(), pandadoc.PandocError)
True
You can find a full list of exceptions in the pandadoc.exceptions module.


Explanation
The pandoc command-line tool works like this:
pandoc [OPTIONS] [FILES]
In addition to the OPTIONS
(documented here),
you can provide either some FILES, or some input text (via stdin).
The call_pandoc function of pandadoc works in a similar way:

The options argument contains a list of pandoc options.
E.g. ["-f", "markdown", "-t", "html"].
The files argument is a list of file paths (or absolute URIs).
E.g. ["path/to/file.md", "https://www.fsf.org"]
The input_text argument is used as text input to pandoc.
E.g. # Simple Doc\n\nA simple markdown document\n.

The timeout and decode arguments are used to control whether the pandoc
process times out, and whether the result should be decoded to a str
(True by default).


Bugs/Requests
Please use the GitHub issue tracker
to submit bugs or request features.
Feedback is always appreciated.


License
Distributed under the
MIT license.