Metadata-Version: 1.1
Name: pypandoc
Version: 1.2.0
Summary: Thin wrapper for pandoc.
Home-page: https://github.com/bebraw/pypandoc
Author: Juho Vepsäläinen
Author-email: bebraw@gmail.com
License: MIT
Description: pypandoc
        ========
        
        |Build Status| |PyPI version| |conda version|
        
        pypandoc provides a thin wrapper for
        `pandoc <http://johnmacfarlane.net/pandoc/>`__, a universal document
        converter.
        
        Installation
        ------------
        
        pypandoc uses ``pandoc``, so it needs an available installation of
        ``pandoc``. For some common cases (wheels, conda packages), pypandoc
        already includes ``pandoc`` (and ``pandoc_citeproc``) in it's prebuilt
        package.
        
        If ``pandoc`` is already installed (``pandoc`` is in the PATH),
        ``pypandoc`` uses the version with the higher version number and if both
        are the same, the already installed version. See `Specifying the
        location of pandoc binaries <#specifying_binaries>`__ for more.
        
        To use ``pandoc`` filters, you must have the relevant filter installed
        on your machine.
        
        Installing via pip
        ~~~~~~~~~~~~~~~~~~
        
        Install via ``pip install pypandoc``.
        
        Prebuilt `wheels for Windows and Mac OS
        X <https://pypi.python.org/pypi/pypandoc/>`__ include pandoc. If there
        is no prebuilt binary available, you have to `install ``pandoc``
        yourself <#installing-pandoc>`__.
        
        If you use Linux and have `your own
        wheelhouse <http://wheel.readthedocs.org/en/latest/#usage>`__, you can
        build a wheel which include ``pandoc`` with
        ``python setup.py download_pandoc; python setup.py bdist_wheel``. Be
        aware that this works only on 64bit intel systems, as we only download
        it from the `official
        source <https://github.com/jgm/pandoc/releases>`__.
        
        Installing via conda
        ~~~~~~~~~~~~~~~~~~~~
        
        ``pypandoc`` is included in
        `conda-forge <https://conda-forge.github.io/>`__. The conda packages
        will also install the ``pandoc`` package, so ``pandoc`` is available in
        the installation.
        
        Install via ``conda install -c conda-forge pypandoc``.
        
        You can also add the channel to your conda config via
        ``conda config --add channels conda-forge``. This makes it possible to
        use ``conda install pypandoc`` directly and also lets you update via
        ``conda update pypandoc``.
        
        Installing pandoc
        ~~~~~~~~~~~~~~~~~
        
        If you don't get ``pandoc`` installed via a prebuild wheel which
        includes ``pandoc`` or via the conda package dependencies, you need to
        install ``pandoc`` by yourself.
        
        Installing pandoc via pypandoc
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Installing via pypandoc is possible on Windows, Mac OS X or Linux
        (Intel-based):
        
        .. code:: python
        
            # expects a installed pypandoc: pip install pypandoc
            from pypandoc.pandoc_download import download_pandoc
            # see the documentation how to customize the installation path
            # but be aware that you then need to include it in the PATH
            download_pandoc()
        
        The default install location is included in the search path for
        ``pandoc``, so you don't need to add it to ``PATH``.
        
        Installing pandoc manually
        ^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Installing manually via the system mechanism is also possible. Such
        installation mechanism make ``pandoc`` available on many more platforms:
        
        -  Ubuntu/Debian: ``sudo apt-get install pandoc``
        -  Fedora/Red Hat: ``sudo yum install pandoc``
        -  Arch: ``sudo pacman -S pandoc``
        -  Mac OS X with Homebrew:
           ``brew install pandoc pandoc-citeproc Caskroom/cask/mactex``
        -  Machine with Haskell: ``cabal-install pandoc``
        -  Windows: There is an installer available
           `here <http://johnmacfarlane.net/pandoc/installing.html>`__
        -  `FreeBSD port <http://www.freshports.org/textproc/pandoc/>`__
        -  Or see http://johnmacfarlane.net/pandoc/installing.html
        
        Be aware that not all install mechanismen put ``pandoc`` in ``PATH``, so
        you either have to change ``PATH`` yourself or set the full path to
        ``pandoc`` in ``PYPANDOC_PANDOC``. See the next section for more
        information.
        
        Specifying the location of pandoc binaries
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        You can point to a specific pandoc version by setting the environment
        variable ``PYPANDOC_PANDOC`` to the full path to the pandoc binary
        (``PYPANDOC_PANDOC=/home/x/whatever/pandoc`` or
        ``PYPANDOC_PANDOC=c:\pandoc\pandoc.exe``). If this environment variable
        is set, this is the only place where pandoc is searched for.
        
        In certain cases, e.g. pandoc is installed but a web server with its own
        user cannot find the binaries, it is useful to specify the location at
        runtime:
        
        .. code:: python
        
            import os
            os.environ.setdefault('PYPANDOC_PANDOC', '/home/x/whatever/pandoc')
        
        Usage
        -----
        
        There are two basic ways to use ``pypandoc``: with input files or with
        input strings.
        
        .. code:: python
        
            import pypandoc
        
            # With an input file: it will infer the input format from the filename
            output = pypandoc.convert_file('somefile.md', 'rst')
        
            # ...but you can overwrite the format via the `format` argument:
            output = pypandoc.convert_file('somefile.txt', 'rst', format='md')
        
            # alternatively you could just pass some string. In this case you need to
            # define the input format:
            output = pypandoc.convert_text('#some title', 'rst', format='md')
            # output == 'some title\r\n==========\r\n\r\n'
        
        ``convert_text`` expects this string to be unicode or utf-8 encoded
        bytes. ``convert_*`` will always return a unicode string.
        
        It's also possible to directly let ``pandoc`` write the output to a
        file. This is the only way to convert to some output formats (e.g. odt,
        docx, epub, epub3, pdf). In that case ``convert_*()`` will return an
        empty string.
        
        .. code:: python
        
            import pypandoc
        
            output = pypandoc.convert_file('somefile.md', 'docx', outputfile="somefile.docx")
            assert output == ""
        
        In addition to ``format``, it is possible to pass ``extra_args``. That
        makes it possible to access various ``pandoc`` options easily.
        
        .. code:: python
        
            output = pypandoc.convert_text(
                '<h1>Primary Heading</h1>',
                'md', format='html',
                extra_args=['--atx-headers'])
            # output == '# Primary Heading\r\n'
            output = pypandoc.convert(
                '# Primary Heading',
                'html', format='md',
                extra_args=['--base-header-level=2'])
            # output == '<h2 id="primary-heading">Primary Heading</h2>\r\n'
        
        pypandoc now supports easy addition of `pandoc
        filters <http://johnmacfarlane.net/pandoc/scripting.html>`__.
        
        .. code:: python
        
            filters = ['pandoc-citeproc']
            pdoc_args = ['--mathjax',
                         '--smart']
            output = pd.convert_file(source=filename,
                                     to='html5',
                                     format='md',
                                     extra_args=pdoc_args,
                                     filters=filters)
        
        Please pass any filters in as a list and not as a string.
        
        Please refer to ``pandoc -h`` and the `official
        documentation <http://johnmacfarlane.net/pandoc/README.html>`__ for
        further details.
        
            Note: the old way of using ``convert(input, output)`` is deprecated
            as in some cases it wasn't possible to determine whether the input
            should be used as a filename or as text.
        
        Dealing with Formatting Arguments
        ---------------------------------
        
        Pandoc supports custom formatting though ``-V`` parameter. In order to
        use it through pypandoc, use code such as this:
        
        .. code:: python
        
            output = pypandoc.convert_file('demo.md', 'pdf', outputfile='demo.pdf',
              extra_args=['-V', 'geometry:margin=1.5cm'])
        
            Note: it's important to separate ``-V`` and its argument within a
            list like that or else it won't work. This gotcha has to do with the
            way
            ```subprocess.Popen`` <https://docs.python.org/2/library/subprocess.html#subprocess.Popen>`__
            works.
        
        Getting Pandoc Version
        ----------------------
        
        As it can be useful sometimes to check what Pandoc version is available
        at your system or which particular ``pandoc`` binary is used by
        ``pypandoc``. For that, ``pypandoc`` provides the following utility
        functions. Example:
        
        ::
        
            print(pypandoc.get_pandoc_version())
            print(pypandoc.get_pandoc_path())
            print(pypandoc.get_pandoc_formats())
        
        Related
        -------
        
        -  `pydocverter <https://github.com/msabramo/pydocverter>`__ is a client
           for a service called `Docverter <http://www.docverter.com/>`__, which
           offers ``pandoc`` as a service (plus some extra goodies).
        -  See `pyandoc <http://pypi.python.org/pypi/pyandoc/>`__ for an
           alternative implementation of a ``pandoc`` wrapper from Kenneth
           Reitz. This one hasn't been active in a while though.
        
        Contributing
        ------------
        
        Contributions are welcome. When opening a PR, please keep the following
        guidelines in mind:
        
        1. Before implementing, please open an issue for discussion.
        2. Make sure you have tests for the new logic.
        3. Make sure your code passes ``flake8 pypandoc/*.py tests.py``
        4. Add yourself to contributors at ``README.md`` unless you are already
           there. In that case tweak your contributions.
        
        Note that for citeproc tests to pass you'll need to have
        `pandoc-citeproc <https://github.com/jgm/pandoc-citeproc>`__ installed.
        If you installed a prebuilt wheel or conda package, it is already
        included.
        
        Contributors
        ------------
        
        -  `Valentin Haenel <https://github.com/esc>`__ - String conversion fix
        -  `Daniel Sanchez <https://github.com/ErunamoJAZZ>`__ - Automatic
           parsing of input/output formats
        -  `Thomas G. <https://github.com/coldfix>`__ - Python 3 support
        -  `Ben Jao Ming <https://github.com/benjaoming>`__ - Fail gracefully if
           ``pandoc`` is missing
        -  `Ross Crawford-d'Heureuse <http://github.com/rosscdh>`__ - Encode
           input in UTF-8 and add Django example
        -  `Michael Chow <https://github.com/machow>`__ - Decode output in UTF-8
        -  `Janusz Skonieczny <https://github.com/wooyek>`__ - Support Windows
           newlines and allow encoding to be specified.
        -  `gabeos <https://github.com/gabeos>`__ - Fix help parsing
        -  `Marc Abramowitz <https://github.com/msabramo>`__ - Make ``setup.py``
           fail hard if ``pandoc`` is missing, Travis, Dockerfile, PyPI badge,
           Tox, PEP-8, improved documentation
        -  `Daniel L. <https://github.com/mcktrtl>`__ - Add ``extra_args``
           example to README
        -  `Amy Guy <https://github.com/rhiaro>`__ - Exception handling for
           unicode errors
        -  `Florian Eßer <https://github.com/flesser>`__ - Allow Markdown
           extensions in output format
        -  `Philipp Wendler <https://github.com/PhilippWendler>`__ - Allow
           Markdown extensions in input format
        -  `Jan Schulz <https://github.com/JanSchulz>`__ - Handling output to a
           file, Travis to work on newer version of Pandoc, return code
           checking, get\_pandoc\_version. Helped to fix the Travis build, new
           ``convert_*`` API
        -  `Aaron Gonzales <https://github.com/xysmas>`__ - Added better filter
           handling
        -  `David Lukes <https://github.com/dlukes>`__ - Enabled input from
           non-plain-text files and made sure tests clean up template files
           correctly if they fail
        -  `valholl <https://github.com/valholl>`__ - Set up licensing
           information correctly and include examples to distribution version
        -  `Cyrille Rossant <https://github.com/rossant>`__ - Fixed bug by
           trimming out stars in the list of ``pandoc`` formats. Helped to fix
           the Travis build.
        -  `Paul Osborne <https://github.com/posborne>`__ - Don't require
           ``pandoc`` to install pypandoc.
        -  `Felix Yan <https://github.com/felixonmars>`__ - Added installation
           instructions for Arch Linux.
        
        License
        -------
        
        ``pypandoc`` is available under MIT license. See LICENSE for more
        details. ``pandoc`` itself is `available under the GPL2
        license <https://github.com/jgm/pandoc/blob/master/COPYING>`__.
        
        .. |Build Status| image:: https://travis-ci.org/bebraw/pypandoc.svg?branch=master
           :target: https://travis-ci.org/bebraw/pypandoc
        .. |PyPI version| image:: https://badge.fury.io/py/pypandoc.svg
           :target: https://pypi.python.org/pypi/pypandoc/
        .. |conda version| image:: https://anaconda.org/conda-forge/pypandoc/badges/version.svg
           :target: https://anaconda.org/conda-forge/pypandoc/
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Topic :: Text Processing
Classifier: Topic :: Text Processing :: Filters
