Metadata-Version: 1.1
Name: pypandoc
Version: 1.0.4
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
        ========
        
        |Latest Version| |Build Status|
        
        pypandoc provides a thin wrapper for
        `pandoc <http://johnmacfarlane.net/pandoc/>`__, a universal document
        converter.
        
        Installation
        ------------
        
        -  Install pandoc
        -  Ubuntu/Debian: ``sudo apt-get install pandoc``
        -  Fedora/Red Hat: ``sudo yum install pandoc``
        -  Mac OS X with Homebrew: ``brew install pandoc``
        -  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
        -  ``pip install pypandoc``
        -  To use pandoc filters, you must have the relevant filter installed on
           your machine
        
        Usage
        -----
        
        The basic invocation looks like this:
        ``pypandoc.convert('input', 'output format')``. ``pypandoc`` tries to
        infer the type of the input automatically. If it's a file, it will load
        it. In case you pass a string, you can define the ``format`` using the
        parameter. The example below should clarify the usage:
        
        .. code:: python
        
            import pypandoc
        
            output = pypandoc.convert('somefile.md', 'rst')
        
            # alternatively you could just pass some string to it and define its format
            output = pypandoc.convert('#some title', 'rst', format='md')
            # output == 'some title\r\n==========\r\n\r\n'
        
        If you pass in a string (and not a filename), ``convert`` 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('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(
                '<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(source=filename,
                                to='html5',
                                format='md',
                                extra_args=pdoc_args,
                                filters=filters)
        
        Please pass any filters in as a list and not a string.
        
        Please refer to ``pandoc -h`` and the `official
        documentation <http://johnmacfarlane.net/pandoc/README.html>`__ for
        further details.
        
        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('demo.md', 'pdf', outputfile='demo.pdf',
              extra_args=['-V', 'geometry:margin=1.5cm'])
        
        Note that 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`` works.
        
        Getting Pandoc Version
        ----------------------
        
        As it can be useful sometimes to check what Pandoc version is available
        at your system, ``pypandoc`` provides an utility for this. Example:
        
        ::
        
            version = pypandoc.get_pandoc_version()
        
        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). It has the same
        API as pypandoc, so you can easily write code that uses one and falls
        back to the other. E.g.:
        
        .. code:: python
        
            try:
                import pypandoc as converter
            except ImportError:
                import pydocverter as converter
        
            converter.convert('somefile.md', 'rst')
        
        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.
        
            IMPORTANT! Currently Travis build is a bit broken. If you have any
            idea on how to debug that, please see
            `#55 <https://github.com/bebraw/pypandoc/issues/55>`__.
        
        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.
        -  `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.
        
        License
        -------
        
        ``pypandoc`` is available under MIT license. See LICENSE for more
        details.
        
        .. |Latest Version| image:: https://pypip.in/version/pypandoc/badge.svg
           :target: https://pypi.python.org/pypi/pypandoc/
        .. |Build Status| image:: https://travis-ci.org/bebraw/pypandoc.svg?branch=master
           :target: https://travis-ci.org/bebraw/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
