├── .github
    └── workflows
    │   └── ci.yaml
├── .gitignore
├── Dockerfile
├── LICENSE
├── MANIFEST.in
├── README.md
├── docker-compose.yml
├── examples
    └── services.py
├── filter_test.md
├── md
├── poetry.lock
├── pypandoc
    ├── __init__.py
    ├── handler.py
    ├── pandoc_download.py
    └── py3compat.py
├── pyproject.toml
├── release.md
├── setup.py
├── setup_binary.py
├── tea.yaml
├── test.md
├── test_data
    ├── index.html
    ├── test.docx
    └── test.png
└── tests.py


/.github/workflows/ci.yaml:
--------------------------------------------------------------------------------
  1 | name: Continuous Integration
  2 | 
  3 | on: [push, pull_request]
  4 | 
  5 | 
  6 | defaults:
  7 |   run:
  8 |     shell: bash
  9 | 
 10 | concurrency:
 11 |   group: ci-tests-${{ github.ref }}-1
 12 |   cancel-in-progress: true
 13 |   
 14 | jobs:
 15 |   test:
 16 |     strategy:
 17 |       fail-fast: false
 18 |       matrix:
 19 |         os: [ubuntu-20.04, ubuntu-22.04, macos-13, windows-2022]
 20 |         python-version: [ "3.7", "3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "pypy3.8", "pypy3.9", "pypy3.10", ]
 21 |     runs-on: ${{ matrix.os }}
 22 |     steps:
 23 |       - name: Check out repository
 24 |         uses: actions/checkout@v4
 25 |       - name: Set up python
 26 |         id: setup-python
 27 |         uses: actions/setup-python@v5
 28 |         with:
 29 |           python-version: ${{ matrix.python-version }}
 30 |       - name: Print Python Information
 31 |         run: python -VV
 32 |       - name: install TinyTeX
 33 |         uses: r-lib/actions/setup-tinytex@v2
 34 |       - name: Install and configure Poetry
 35 |         run: |
 36 |           pip3 install -U poetry setuptools
 37 |           poetry config virtualenvs.in-project true
 38 |       - name: Set up cache
 39 |         uses: actions/cache@v4
 40 |         id: cached-poetry-dependencies
 41 |         with:
 42 |           path: .venv
 43 |           key: venv-${{ runner.os }}-${{ runner.arch }}-${{ steps.full-python-version.outputs.version }}-${{ hashFiles('**/poetry.lock') }}
 44 |       - name: Install dependencies
 45 |         run: poetry install
 46 |         if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
 47 |       - name: Download pandoc
 48 |         run: GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} poetry run python setup_binary.py download_pandoc
 49 |       - name: run tests
 50 |         run: poetry run python tests.py
 51 | 
 52 |   builder_pypandoc:
 53 |     needs: [test]
 54 |     runs-on: ubuntu-20.04  # Any OS is fine as this wheel is not OS dependent
 55 |     steps:
 56 |       - name: Check out repository
 57 |         uses: actions/checkout@v4
 58 |       - name: Set up python
 59 |         id: setup-python
 60 |         uses: actions/setup-python@v5
 61 |         with:
 62 |           python-version: 3.9  # Build any 1 python version as this wheel is not version dependent
 63 |       - name: Update dependencies
 64 |         run: python -m pip install -U pip wheel setuptools
 65 |       - name: Build wheel
 66 |         run: python setup.py sdist bdist_wheel
 67 |       - name: Upload artifacts
 68 |         uses: actions/upload-artifact@v4
 69 |         with:
 70 |           name: pypandoc-distributions
 71 |           path: dist/
 72 | 
 73 |   builder_pypandoc_binary:
 74 |     needs: [test]
 75 |     strategy:
 76 |       matrix:
 77 |         os: [macos-14, windows-2022, ubuntu-22.04]
 78 |     runs-on: ${{ matrix.os }}
 79 |     steps:
 80 |       - name: Check out repository
 81 |         uses: actions/checkout@v4
 82 |       - name: Set up QEMU
 83 |         if: runner.os == 'Linux'
 84 |         uses: docker/setup-qemu-action@v3
 85 |         with:
 86 |           platforms: all
 87 |       - name: Remove pyproject and use setuptools
 88 |         run: rm pyproject.toml
 89 |       - name: Build binary Archive
 90 |         uses: pypa/cibuildwheel@v2.16.5
 91 |         env:
 92 |           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 93 |           CIBW_BEFORE_ALL: "python3 -m pip install --break-system-packages setuptools && mv setup_binary.py setup.py && python3 setup.py download_pandoc"
 94 |           CIBW_BUILD: cp39-*  # Build any 1 python version as this wheel is not version dependent
 95 |           # We skip some variants because:
 96 |           # - pandoc does not publish binaries for Linux 32bit
 97 |           CIBW_ARCHS_LINUX: "auto64 aarch64"
 98 |           CIBW_ARCHS_MACOS: "x86_64 arm64"
 99 |           CIBW_ARCHS_WINDOWS: "AMD64" 
100 |       - name: Upload artifacts
101 |         uses: actions/upload-artifact@v4
102 |         with:
103 |           name: pypandoc-binary-${{ matrix.os }}-distributions
104 |           path: wheelhouse/
105 | 
106 |   publisher_release:
107 |     needs: [builder_pypandoc, builder_pypandoc_binary]
108 |     if: startsWith(github.ref, 'refs/tags/v')
109 |     runs-on: ubuntu-latest
110 |     permissions:
111 |       id-token: write
112 |     steps:
113 |       - name: Check out repository
114 |         uses: actions/checkout@v4
115 |       - name: Download artifacts
116 |         uses: actions/download-artifact@v4
117 |         with:
118 |           path: dist/
119 |           merge-multiple: true
120 |       - name: Publish  to PyPI
121 |         uses: pypa/gh-action-pypi-publish@release/v1
122 |         with:
123 |           verbose: true
124 | 
125 | 
126 |   publisher_latest:
127 |     needs: [builder_pypandoc, builder_pypandoc_binary]
128 |     if: github.ref == 'refs/heads/master'
129 |     runs-on: ubuntu-latest
130 |     steps:
131 |       - name: Check out repository
132 |         uses: actions/checkout@v4
133 |       - name: Download artifacts
134 |         uses: actions/download-artifact@v4
135 |         with:
136 |           path: dist/
137 |           merge-multiple: true
138 |       - name: Make release
139 |         uses: "marvinpinto/action-automatic-releases@v1.2.1"
140 |         with:
141 |           repo_token: "${{ secrets.GITHUB_TOKEN }}"
142 |           prerelease: true
143 |           title: "Latest Development Version"
144 |           automatic_release_tag: "latest"
145 |           files: dist/*
146 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
 1 | |.egg-info
 2 | *.swp
 3 | *.pyc
 4 | dist/
 5 | pypandoc.egg-info/
 6 | .tox/
 7 | 
 8 | ## IDEs
 9 | # pycharm
10 | .idea/
11 | 
12 | # downloaded pandoc packages
13 | pandoc-*.msi
14 | pandoc-*.deb
15 | pandoc-*.pkg
16 | # The downloaded files end up here
17 | pypandoc/files/
18 | build/
19 | 


--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
 1 | # --------------------------------------------------------------------------
 2 | # This is a Dockerfile to build a Debian image with pypandoc and pandoc.
 3 | #
 4 | # Use a command like:
 5 | #     docker build -t <user>/pypandoc .
 6 | # --------------------------------------------------------------------------
 7 | 
 8 | FROM  python:3.12
 9 | LABEL author  Jessica Tegner <jessica@jessicategner.com> and pypandoc contributors
10 | # Update apt packages and install pandoc
11 | RUN apt update && apt upgrade -y && apt install pandoc -y
12 | # Update pip
13 | RUN pip install --upgrade pip
14 | 
15 | # Copy the files to container   
16 | COPY . pypandoc
17 | WORKDIR pypandoc
18 | 
19 | # Use pip to install the local version of pypandoc using pyproject.toml
20 | RUN pip install .
21 | 
22 | RUN mkdir -p /source
23 | WORKDIR /source
24 | 
25 | CMD ["/usr/bin/python"]
26 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | Copyright (c) 2011 Juho Vepsäläinen
 2 | 
 3 | Permission is hereby granted, free of charge, to any person obtaining
 4 | a copy of this software and associated documentation files (the
 5 | "Software"), to deal in the Software without restriction, including
 6 | without limitation the rights to use, copy, modify, merge, publish,
 7 | distribute, sublicense, and/or sell copies of the Software, and to
 8 | permit persons to whom the Software is furnished to do so, subject to
 9 | the following conditions:
10 | 
11 | The above copyright notice and this permission notice shall be
12 | included in all copies or substantial portions of the Software.
13 | 
14 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18 | LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20 | WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21 | 
22 | compat code from IPython py3compat.py and encoding.py, which is licensed
23 | the terms of the Modified BSD License (also known as New or
24 | Revised or 3-Clause BSD)
25 | 
26 | - Copyright (c) 2008-2014, IPython Development Team
27 | - Copyright (c) 2001-2007, Fernando Perez <fernando.perez@colorado.edu>
28 | - Copyright (c) 2001, Janko Hauser <jhauser@zscout.de>
29 | - Copyright (c) 2001, Nathaniel Gray <n8gray@caltech.edu>
30 | 
31 | All rights reserved.
32 | 
33 | Redistribution and use in source and binary forms, with or without
34 | modification, are permitted provided that the following conditions are
35 | met:
36 | 
37 | Redistributions of source code must retain the above copyright notice,
38 | this list of conditions and the following disclaimer.
39 | 
40 | Redistributions in binary form must reproduce the above copyright notice,
41 | this list of conditions and the following disclaimer in the documentation
42 | and/or other materials provided with the distribution.
43 | 
44 | Neither the name of the IPython Development Team nor the names of its
45 | contributors may be used to endorse or promote products derived from this
46 | software without specific prior written permission.
47 | 
48 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
49 | IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
50 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
51 | PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
52 | CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
53 | EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
54 | PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
55 | PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
56 | LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
57 | NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
58 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
59 | 


--------------------------------------------------------------------------------
/MANIFEST.in:
--------------------------------------------------------------------------------
1 | include README.md
2 | include LICENSE
3 | include tests.py
4 | include filter_test.md
5 | include examples/*
6 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # pypandoc
  2 | 
  3 | [![Build Status](https://github.com/JessicaTegner/pypandoc/actions/workflows/ci.yaml/badge.svg)](https://github.com/JessicaTegner/pypandoc/actions/workflows/ci.yaml)
  4 | [![GitHub Releases](https://img.shields.io/github/tag/JessicaTegner/pypandoc.svg)](https://github.com/JessicaTegner/pypandoc/releases)
  5 | [![Pypandoc PyPI Version](https://img.shields.io/pypi/v/pypandoc?label=pypandoc+pypi+version)](https://pypi.org/project/pypandoc/)
  6 | [![Pypandoc Binary PyPI Version](https://img.shields.io/pypi/v/pypandoc_binary?label=pypandoc+binary+pypi+version)](https://pypi.org/project/pypandoc_binary/)
  7 | ![PyPandoc PyPi Downloads](https://img.shields.io/pypi/dm/pypandoc)
  8 | ![PyPandoc Binary PyPI Downloads](https://img.shields.io/pypi/dm/pypandoc_binary)
  9 | [![conda version](https://anaconda.org/conda-forge/pypandoc/badges/version.svg)](https://anaconda.org/conda-forge/pypandoc/)
 10 | [![Development Status](https://img.shields.io/pypi/status/pypandoc.svg)](https://pypi.python.org/pypi/pypandoc/)
 11 | [![PyPandoc Python version](https://img.shields.io/pypi/pyversions/pypandoc.svg)](https://pypi.python.org/pypi/pypandoc/)
 12 | [![PyPandoc Binary Python version](https://img.shields.io/pypi/pyversions/pypandoc_binary.svg)](https://pypi.python.org/pypi/pypandoc_binary/)
 13 | ![License](https://img.shields.io/pypi/l/pypandoc.svg)
 14 | 
 15 | Pypandoc provides a thin wrapper for [pandoc](https://pandoc.org), a universal
 16 | document converter.
 17 | 
 18 | ## Installation
 19 | 
 20 | Pypandoc uses pandoc, so it needs an available installation of pandoc. Pypandoc provides 2 packages, "pypandoc" and "pypandoc_binary", with the second one including pandoc out of the box.
 21 | The 2 packages are identical, with the only difference being that one includes pandoc, while the other don't.
 22 | 
 23 | If pandoc is already installed (i.e. pandoc is in the `PATH`), pypandoc uses the version with the
 24 | higher version number, and if both are the same, the already installed version. See [Specifying the location of pandoc binaries](#specifying-the-location-of-pandoc-binaries) for more.
 25 | 
 26 | To use pandoc filters, you must have the relevant filters installed on your machine.
 27 | 
 28 | ### Installing via pip
 29 | 
 30 | If you [want to install pandoc yourself](#Installing-pandoc) or are on a unsupported platform, you'll need to install "pypandoc" and  [install pandoc manually](#Installing-pandoc)
 31 | 
 32 | ```
 33 | pip install pypandoc
 34 | ```
 35 | 
 36 | 
 37 | If you want pandoc included out of the box, you can utilize our pypandoc_binary package, which are identical to the "pypandoc" package, but with pandoc included.
 38 | 
 39 | ```
 40 | pip install pypandoc_binary
 41 | ```
 42 | 
 43 | Prebuilt [wheels for Windows and Mac OS X](https://pypi.python.org/pypi/pypandoc_binary/)
 44 | 
 45 | If you use Linux and have [your own wheelhouse](https://wheel.readthedocs.org/en/latest/#usage),
 46 | you can build a wheel which include pandoc with
 47 | `python setup_binary.py download_pandoc; python setup.py bdist_wheel`. Be aware that this works only
 48 | on 64bit intel systems, as we only download it from the
 49 | [official releases](https://github.com/jgm/pandoc/releases).
 50 | 
 51 | ### Installing via conda
 52 | 
 53 | Pypandoc is included in [conda-forge](https://conda-forge.github.io/). The conda packages will
 54 | also install the pandoc package, so pandoc is available in the installation.
 55 | 
 56 | Install via `conda install -c conda-forge pypandoc`.
 57 | 
 58 | You can also add the channel to your conda config via
 59 | `conda config --add channels conda-forge`. This makes it possible to
 60 | use `conda install pypandoc` directly and also lets you update via `conda update pypandoc`.
 61 | 
 62 | ### Installing pandoc
 63 | 
 64 | If you don't already have pandoc on your system, or have installed the pypandoc_binary package, which includes pandoc, you need to install pandoc by yourself.
 65 | 
 66 | #### Installing pandoc via pypandoc
 67 | 
 68 | Installing via pypandoc is possible on Windows, Mac OS X or Linux (Intel-based, 64-bit):
 69 | 
 70 | ```python
 71 | pip install pypandoc
 72 | from pypandoc.pandoc_download import download_pandoc
 73 | # see the documentation how to customize the installation path
 74 | # but be aware that you then need to include it in the `PATH`
 75 | download_pandoc()
 76 | ```
 77 | 
 78 | The default install location is included in the search path for pandoc, so you
 79 | don't need to add it to the `PATH`.
 80 | 
 81 | By default, the latest pandoc version is installed. If you want to specify your own version, say 1.19.1, use `download_pandoc(version='1.19.1')` instead.
 82 | 
 83 | #### Installing pandoc manually
 84 | 
 85 | Installing manually via the system mechanism is also possible. Such installation mechanism
 86 | make pandoc available on many more platforms:
 87 | 
 88 | - Ubuntu/Debian: `sudo apt-get install pandoc`
 89 | - Fedora/Red Hat: `sudo yum install pandoc`
 90 | - Arch: `sudo pacman -S pandoc`
 91 | - Mac OS X with Homebrew: `brew install pandoc pandoc-citeproc Caskroom/cask/mactex`
 92 | - Machine with Haskell: `cabal-install pandoc`
 93 | - Windows: There is an installer available
 94 |   [here](https://pandoc.org/installing.html)
 95 | - [FreeBSD with pkg:](https://www.freshports.org/textproc/hs-pandoc/) `pkg install hs-pandoc`
 96 | - Or see [Pandoc - Installing pandoc](https://pandoc.org/installing.html)
 97 | 
 98 | Be aware that not all install mechanisms put pandoc in the `PATH`, so you either
 99 | have to change the `PATH` yourself or set the full `PATH` to pandoc in
100 | `PYPANDOC_PANDOC`. See the next section for more information.
101 | 
102 | ### Specifying the location of pandoc binaries
103 | 
104 | You can point to a specific pandoc version by setting the environment variable
105 | `PYPANDOC_PANDOC` to the full `PATH` to the pandoc binary
106 | (`PYPANDOC_PANDOC=/home/x/whatever/pandoc` or `PYPANDOC_PANDOC=c:\pandoc\pandoc.exe`).
107 | If this environment variable is set, this is the only place where pandoc is searched for.
108 | 
109 | In certain cases, e.g. pandoc is installed but a web server with its own user
110 | cannot find the binaries, it is useful to specify the location at runtime:
111 | 
112 | ```python
113 | import os
114 | os.environ.setdefault('PYPANDOC_PANDOC', '/home/x/whatever/pandoc')
115 | ```
116 | 
117 | ## Usage
118 | 
119 | There are two basic ways to use pypandoc: with input files or with input
120 | strings.
121 | 
122 | 
123 | ```python
124 | import pypandoc
125 | 
126 | # With an input file: it will infer the input format from the filename
127 | output = pypandoc.convert_file('somefile.md', 'rst')
128 | 
129 | # ...but you can overwrite the format via the `format` argument:
130 | output = pypandoc.convert_file('somefile.txt', 'rst', format='md')
131 | 
132 | # alternatively you could just pass some string. In this case you need to
133 | # define the input format:
134 | output = pypandoc.convert_text('# some title', 'rst', format='md')
135 | # output == 'some title\r\n==========\r\n\r\n'
136 | ```
137 | 
138 | `convert_text` expects this string to be unicode or utf-8 encoded bytes. `convert_*` will always
139 | return a unicode string.
140 | 
141 | It's also possible to directly let pandoc write the output to a file. This is the only way to
142 | convert to some output formats (e.g. odt, docx, epub, epub3, pdf). In that case `convert_*()` will
143 | return an empty string.
144 | 
145 | ```python
146 | import pypandoc
147 | 
148 | output = pypandoc.convert_file('somefile.md', 'docx', outputfile="somefile.docx")
149 | assert output == ""
150 | ```
151 | 
152 | 
153 | It's also possible to specify multiple input files to pandoc, either as absolute paths, relative paths or file patterns.
154 | 
155 | ```python
156 | import pypandoc
157 | 
158 | # convert all markdown files in a chapters/ subdirectory.
159 | pypandoc.convert_file('chapters/*.md', 'docx', outputfile="somefile.docx")
160 | 
161 | # convert all markdown files in the book1 and book2 directories.
162 | pypandoc.convert_file(['book1/*.md', 'book2/*.md'], 'docx', outputfile="somefile.docx")
163 | 
164 | # convert the front from another drive, and all markdown files in the chapter directory.
165 | pypandoc.convert_file(['D:/book_front.md', 'book2/*.md'], 'docx', outputfile="somefile.docx")
166 | ```
167 | 
168 | 
169 | pathlib is also supported.
170 | 
171 | ```python
172 | import pypandoc
173 | from pathlib import Path
174 | 
175 | # single file
176 | input = Path('somefile.md')
177 | output = input.with_suffix('.docx')
178 | pypandoc.convert_file(input, 'docx', outputfile=output)
179 | 
180 | # convert all markdown files in a chapters/ subdirectory.
181 | pypandoc.convert_file(Path('chapters').glob('*.md'), 'docx', outputfile="somefile.docx")
182 | 
183 | # convert all markdown files in the book1 and book2 directories.
184 | pypandoc.convert_file([*Path('book1').glob('*.md'), *Path('book2').glob('*.md')], 'docx', outputfile="somefile.docx")
185 | # pathlib globs must be unpacked if they are inside lists.
186 | ```
187 | 
188 | In addition to `format`, it is possible to pass `extra_args`.
189 | That makes it possible to access various pandoc options easily.
190 | 
191 | ```python
192 | output = pypandoc.convert_text(
193 |     '<h1>Primary Heading</h1>',
194 |     'md', format='html',
195 |     extra_args=['--atx-headers'])
196 | # output == '# Primary Heading\r\n'
197 | output = pypandoc.convert_text(
198 |     '# Primary Heading',
199 |     'html', format='md',
200 |     extra_args=['--base-header-level=2'])
201 | # output == '<h2 id="primary-heading">Primary Heading</h2>\r\n'
202 | ```
203 | 
204 | pypandoc now supports easy addition of
205 | [pandoc filters](https://pandoc.org/scripting.html).
206 | 
207 | ```python
208 | filters = ['pandoc-citeproc']
209 | pdoc_args = ['--mathjax',
210 |              '--smart']
211 | output = pypandoc.convert_file(filename,
212 |                                to='html5',
213 |                                format='md',
214 |                                extra_args=pdoc_args,
215 |                                filters=filters)
216 | ```
217 | 
218 | Please pass any filters in as a list and not as a string.
219 | 
220 | Please refer to `pandoc -h` and the
221 | [official documentation](https://pandoc.org/MANUAL.html) for further details.
222 | 
223 | ## Dealing with Formatting Arguments
224 | 
225 | Pandoc supports custom formatting though `-V` parameter. In order to use it through
226 | pypandoc, use code such as this:
227 | 
228 | ```python
229 | output = pypandoc.convert_file('demo.md', 'pdf', outputfile='demo.pdf',
230 |   extra_args=['-V', 'geometry:margin=1.5cm'])
231 | ```
232 | 
233 | > Note: it's important to separate `-V` and its argument within a list like that or else
234 | it won't work. This gotcha has to do with the way
235 | [`subprocess.Popen`](https://docs.python.org/2/library/subprocess.html#subprocess.Popen) works.
236 | 
237 | ## Logging Messages
238 | 
239 | Pypandoc logs messages using the [Python logging library](https://docs.python.org/3/library/logging.html).
240 | By default, it will send messages to the console, including any messages 
241 | generated by Pandoc. If desired, this behaviour can be changed by adding
242 | [handlers](https://docs.python.org/3/library/logging.html#handler-objects) to 
243 | the pypandoc logger **before calling any functions**. For example, to mute all 
244 | logging add a [null handler](https://docs.python.org/3/library/logging.handlers.html#nullhandler):
245 | 
246 | ```python
247 | import logging
248 | logging.getLogger('pypandoc').addHandler(logging.NullHandler())
249 | ```
250 | 
251 | ## Getting Pandoc Version
252 | 
253 | As it can be useful sometimes to check what pandoc version is available at your system or which
254 | particular pandoc binary is used by pypandoc. For that, pypandoc provides the following
255 | utility functions. Example:
256 | 
257 | ```
258 | print(pypandoc.get_pandoc_version())
259 | print(pypandoc.get_pandoc_path())
260 | print(pypandoc.get_pandoc_formats())
261 | ```
262 | 
263 | ## Related
264 | 
265 | * [pydocverter](https://github.com/msabramo/pydocverter) is a client for a service called
266 | [Docverter](https://www.docverter.com), which offers pandoc as a service (plus some extra goodies).
267 | * See [pyandoc](https://pypi.python.org/pypi/pyandoc/) for an alternative implementation of a pandoc
268 | wrapper from Kenneth Reitz. This one hasn't been active in a while though.
269 | * See [panflute](https://github.com/sergiocorreia/panflute) which provides `convert_text` similar to pypandoc's. Its focus is on writing and running pandoc filters though.
270 | 
271 | ## Contributing
272 | 
273 | Contributions are welcome. When opening a PR, please keep the following guidelines in mind:
274 | 
275 | 1. Before implementing, please open an issue for discussion.
276 | 2. Make sure you have tests for the new logic.
277 | 3. Make sure your code passes `flake8 pypandoc/*.py tests.py`
278 | 4. Add yourself to contributors at `README.md` unless you are already there. In that case tweak your contributions.
279 | 
280 | 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.
281 | 
282 | ## Contributors
283 | 
284 | * [Jessica Tegner](https://github.com/JessicaTegner) - New maintainer as of 1. Juli 2021
285 | * [Valentin Haenel](https://github.com/esc) - String conversion fix
286 | * [Daniel Sanchez](https://github.com/ErunamoJAZZ) - Automatic parsing of input/output formats
287 | * [Thomas G.](https://github.com/coldfix) - Python 3 support
288 | * [Ben Jao Ming](https://github.com/benjaoming) - Fail gracefully if pandoc is missing
289 | * [Ross Crawford-d'Heureuse](https://github.com/rosscdh) - Encode input in UTF-8 and add Django
290 |   example
291 | * [Michael Chow](https://github.com/machow) - Decode output in UTF-8
292 | * [Janusz Skonieczny](https://github.com/wooyek) - Support Windows newlines and allow encoding to
293 |   be specified.
294 | * [gabeos](https://github.com/gabeos) - Fix help parsing
295 | * [Marc Abramowitz](https://github.com/msabramo) - Make `setup.py` fail hard if pandoc is
296 |   missing, Travis, Dockerfile, PyPI badge, Tox, PEP-8, improved documentation
297 | * [Daniel L.](https://github.com/mcktrtl) - Add `extra_args` example to README
298 | * [Amy Guy](https://github.com/rhiaro) - Exception handling for unicode errors
299 | * [Florian Eßer](https://github.com/flesser) - Allow Markdown extensions in output format
300 | * [Philipp Wendler](https://github.com/PhilippWendler) - Allow Markdown extensions in input format
301 | * [Jan Katins](https://github.com/jankatins) - 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. Former maintainer of pypandoc
302 | * [Aaron Gonzales](https://github.com/xysmas) - Added better filter handling
303 | * [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
304 | * [valholl](https://github.com/valholl) - Set up licensing information correctly and include examples to distribution version
305 | * [Cyrille Rossant](https://github.com/rossant) - Fixed bug by trimming out stars in the list of pandoc formats. Helped to fix the Travis build.
306 | * [Paul Osborne](https://github.com/posborne) - Don't require pandoc to install pypandoc.
307 | * [Felix Yan](https://github.com/felixonmars) - Added installation instructions for Arch Linux.
308 | * [Kolen Cheung](https://github.com/ickc) - Implement `_get_pandoc_urls` for installing arbitrary version as well as the latest version of pandoc. Minor: README, Travis, setup.py.
309 | * [Rebecca Heineman](https://github.com/burgerbecky) - Added scanning code for finding pandoc in Windows
310 | * [Andrew Barraford](https://github.com/abarrafo) - Download destination.
311 | * [Jesse Widner](https://github.com/jwidner) & [Dominic Thorn](https://github.com/domvwt) - Add support for lua filters
312 | * [Alex Kneisel](https://github.com/hey-thanks/) - Added pathlib.Path support to convert_file.
313 | * [Juho Vepsäläinen](https://github.com/bebraw/) - Creator and former maintainer of pypandoc
314 | * [Connor](https://github.com/DisSupEng/) - Updated Dockerfile to Python 3.9 image and added docker compose file
315 | 
316 | ## License
317 | 
318 | 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.md).
319 | 


--------------------------------------------------------------------------------
/docker-compose.yml:
--------------------------------------------------------------------------------
 1 | services:
 2 |   app:
 3 |     image: pypandoc
 4 |     container_name: pypan_container
 5 |     build: .
 6 |     restart: always
 7 |     volumes:
 8 |     # Create a binding mount between the source directory on the host and the container's source code directory.
 9 |     # This means that any updated code will be transfered to the running container
10 |     - .:/pypandoc/
11 |     # This is just to keep the container running. It will allow us to use docker compose exec to go inside the container.
12 |     command: tail -F ./anything
13 | 


--------------------------------------------------------------------------------
/examples/services.py:
--------------------------------------------------------------------------------
 1 | # -*- coding: utf-8 -*-
 2 | """
 3 | Example Services for using pypandoc
 4 | """
 5 | from tempfile import NamedTemporaryFile
 6 | 
 7 | import pypandoc
 8 | 
 9 | 
10 | class BasePandocService(object):
11 |     """
12 |     Base class for converting provided HTML to a doc or docx
13 |     """
14 |     file_object = None
15 | 
16 |     def __init__(self):
17 |         self.service = self.get_service()
18 | 
19 |     def get_service(self):
20 |         return pypandoc
21 | 
22 |     def generate(self, **kwargs):
23 |         raise NotImplementedError
24 | 
25 | 
26 | class PandocPDFService(BasePandocService):
27 |     """
28 |     Generate html to pdf format
29 |     """
30 |     def generate(self, html, **kwargs):
31 |         """
32 |         generate the pdf but needs to be set as tex so pandoc handles it
33 |         correctly see docs: http://johnmacfarlane.net/pandoc/ #search pdf
34 |         """
35 |         from_format = kwargs.get('from_format', 'html')
36 |         to_format = kwargs.get('to_format', 'tex')
37 |         # create temp file
38 |         self.file_object = NamedTemporaryFile(suffix='.pdf')
39 | 
40 |         extra_args = (
41 |             '--smart',
42 |             '--standalone',
43 |             '-o', self.file_object.name
44 |         )
45 |         # generate it using pandoc
46 |         self.service.convert_text(html, to_format, format=from_format, extra_args=extra_args)
47 |         # return the file which is now populated with the docx forms
48 |         return self.file_object
49 | 
50 | 
51 | class PandocDocxService(BasePandocService):
52 |     """
53 |     Generate html to docx format
54 |     """
55 |     def generate(self, html, **kwargs):
56 |         from_format = kwargs.get('from_format', 'html')
57 |         to_format = kwargs.get('to_format', 'docx')
58 |         # create temp file
59 |         self.file_object = NamedTemporaryFile(suffix='.docx')
60 | 
61 |         extra_args = (
62 |             '--smart',
63 |             '--standalone',
64 |             '-o', self.file_object.name
65 |         )
66 |         # generate it using pandoc
67 |         self.service.convert_text(html, to_format, format=from_format, extra_args=extra_args)
68 |         # return the file which is now populated with the docx forms
69 |         return self.file_object
70 | 


--------------------------------------------------------------------------------
/filter_test.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | ## This is an in-header citation in bibyaml format
 3 | ## Example taken from pandoc website
 4 | references:
 5 | - id: fenner2012a
 6 |   title: One-click science marketing
 7 |   author:
 8 |   - family: Fenner
 9 |     given: Martin
10 |   container-title: Nature Materials
11 |   volume: 11
12 |   URL: 'http://dx.doi.org/10.1038/nmat3283'
13 |   DOI: 10.1038/nmat3283
14 |   issue: 4
15 |   publisher: Nature Publishing Group
16 |   page: 261-263
17 |   type: article-journal
18 |   issued:
19 |     year: 2012
20 |     month: 3
21 | ---
22 | 
23 | ## Section ##
24 | 
25 | A reference [@fenner2012a].
26 | 
27 | # References
28 | 


--------------------------------------------------------------------------------
/md:
--------------------------------------------------------------------------------
  1 | <div id="mw-page-base" class="noprint">
  2 | 
  3 | </div>
  4 | 
  5 | <div id="mw-head-base" class="noprint">
  6 | 
  7 | </div>
  8 | 
  9 | <div id="content" class="mw-body" role="main">
 10 | 
 11 | [](){#top}
 12 | <div id="siteNotice">
 13 | 
 14 | </div>
 15 | 
 16 | <div class="mw-indicators">
 17 | 
 18 | </div>
 19 | 
 20 | file URI scheme {#firstHeading .firstHeading lang="en"}
 21 | ===============
 22 | 
 23 | <div id="bodyContent" class="mw-body-content">
 24 | 
 25 | <div id="siteSub">
 26 | 
 27 | From Wikipedia, the free encyclopedia
 28 | 
 29 | </div>
 30 | 
 31 | <div id="contentSub">
 32 | 
 33 | </div>
 34 | 
 35 | <div id="jump-to-nav" class="mw-jump">
 36 | 
 37 | Jump to: [navigation](#mw-head), [search](#p-search)
 38 | 
 39 | </div>
 40 | 
 41 | <div id="mw-content-text" class="mw-content-ltr" lang="en" dir="ltr">
 42 | 
 43 | +--------------------------------------+--------------------------------------+
 44 | | <div style="width:52px">             | <span class="mbox-text-span">This    |
 45 | |                                      | article **needs additional citations |
 46 | | [![](//upload.wikimedia.org/wikipedi | for                                  |
 47 | | a/en/thumb/9/99/Question_book-new.sv | [verification](/wiki/Wikipedia:Verif |
 48 | | g/50px-Question_book-new.svg.png){wi | iability "Wikipedia:Verifiability")* |
 49 | | dth="50"                             | *.                                   |
 50 | | height="39"                          | <span                                |
 51 | | srcset="//upload.wikimedia.org/wikip | class="hide-when-compact">Please     |
 52 | | edia/en/thumb/9/99/Question_book-new | help [improve this                   |
 53 | | .svg/75px-Question_book-new.svg.png  | article](//en.wikipedia.org/w/index. |
 54 | | 1.5x, //upload.wikimedia.org/wikiped | php?title=File_URI_scheme&action=edi |
 55 | | ia/en/thumb/9/99/Question_book-new.s | t){.external                         |
 56 | | vg/100px-Question_book-new.svg.png 2 | .text} by [adding citations to       |
 57 | | x"}](/wiki/File:Question_book-new.sv | reliable                             |
 58 | | g){.image}                           | sources](/wiki/Help:Introduction_to_ |
 59 | |                                      | referencing_with_Wiki_Markup/1 "Help |
 60 | | </div>                               | :Introduction to referencing with Wi |
 61 | |                                      | ki Markup/1").                       |
 62 | |                                      | Unsourced material may be challenged |
 63 | |                                      | and removed.</span> *(October 2012)* |
 64 | |                                      | *([Learn how and when to remove this |
 65 | |                                      | template                             |
 66 | |                                      | message](/wiki/Help:Maintenance_temp |
 67 | |                                      | late_removal "Help:Maintenance templ |
 68 | |                                      | ate removal"))*</span>               |
 69 | +--------------------------------------+--------------------------------------+
 70 | 
 71 | The **file URI scheme** is a [URI
 72 | scheme](/wiki/URI_scheme "URI scheme"){.mw-redirect} specified in [RFC
 73 | 1630](//tools.ietf.org/html/rfc1630){.external .mw-magiclink-rfc} and
 74 | [RFC 1738](//tools.ietf.org/html/rfc1738){.external .mw-magiclink-rfc},
 75 | typically used to retrieve files from within one's own computer. The
 76 | [Internet Engineering Task
 77 | Force](/wiki/Internet_Engineering_Task_Force "Internet Engineering Task Force")
 78 | (IETF) has published a series of [draft
 79 | documents](/wiki/Draft_document "Draft document") obsoleting these RFCs.
 80 | They say that they are trying to define "a syntax that is compatible
 81 | with most extant implementations, while attempting to push towards a
 82 | stricter subset of 'ideal' constructs." Doing so involves the
 83 | [deprecation](/wiki/Deprecation "Deprecation") of some less common or
 84 | outdated constructs, some of which are described below. While they may
 85 | work on some current systems, formulations that are not consistent with
 86 | the [standardization](/wiki/Standardization "Standardization") process
 87 | going forward will not have the useful lifetime that others will. The
 88 | drafts are not final, and should be consulted for up to date
 89 | information.^[\[1\]](#cite_note-1)^
 90 | 
 91 | <div id="toc" class="toc">
 92 | 
 93 | <div id="toctitle">
 94 | 
 95 | Contents
 96 | --------
 97 | 
 98 | </div>
 99 | 
100 | -   [<span class="tocnumber">1</span> <span
101 |     class="toctext">Format</span>](#Format)
102 | -   [<span class="tocnumber">2</span> <span class="toctext">Meaning of
103 |     slash character</span>](#Meaning_of_slash_character)
104 | -   [<span class="tocnumber">3</span> <span
105 |     class="toctext">Examples</span>](#Examples)
106 |     -   [<span class="tocnumber">3.1</span> <span
107 |         class="toctext">Unix</span>](#Unix)
108 |     -   [<span class="tocnumber">3.2</span> <span
109 |         class="toctext">Windows</span>](#Windows)
110 | -   [<span class="tocnumber">4</span> <span
111 |     class="toctext">Implementations</span>](#Implementations)
112 |     -   [<span class="tocnumber">4.1</span> <span
113 |         class="toctext">Windows</span>](#Windows_2)
114 |         -   [<span class="tocnumber">4.1.1</span> <span
115 |             class="toctext">Legacy URLs</span>](#Legacy_URLs)
116 |     -   [<span class="tocnumber">4.2</span> <span class="toctext">Web
117 |         pages</span>](#Web_pages)
118 | -   [<span class="tocnumber">5</span> <span
119 |     class="toctext">References</span>](#References)
120 | -   [<span class="tocnumber">6</span> <span class="toctext">External
121 |     links</span>](#External_links)
122 | 
123 | </div>
124 | 
125 | <span id="Format" class="mw-headline">Format</span><span class="mw-editsection"><span class="mw-editsection-bracket">\[</span>[edit](/w/index.php?title=File_URI_scheme&action=edit&section=1 "Edit section: Format")<span class="mw-editsection-bracket">\]</span></span>
126 | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
127 | 
128 | A file URI takes the form of
129 | 
130 |     file://host/path
131 | 
132 | where ***host*** is the [fully qualified domain
133 | name](/wiki/Fully_qualified_domain_name "Fully qualified domain name")
134 | of the system on which the *path* is accessible, and ***path*** is a
135 | hierarchical directory path of the form
136 | *directory*/*directory*/.../*name*. If *host* is omitted, it is taken to
137 | be "[localhost](/wiki/Localhost "Localhost")", the machine from which
138 | the URL is being interpreted. Note that when omitting host, the slash is
139 | not omitted (while "file:///foo.txt" is valid, "file://foo.txt" is not,
140 | although some interpreters manage to handle the latter).
141 | 
142 | \[[RFC 3986](//tools.ietf.org/html/rfc3986){.external
143 | .mw-magiclink-rfc}\] includes additional information about the treatment
144 | of ".." and "." segments in URIs.
145 | 
146 | <span id="Meaning_of_slash_character" class="mw-headline">Meaning of slash character</span><span class="mw-editsection"><span class="mw-editsection-bracket">\[</span>[edit](/w/index.php?title=File_URI_scheme&action=edit&section=2 "Edit section: Meaning of slash character")<span class="mw-editsection-bracket">\]</span></span>
147 | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
148 | 
149 | The **slash character** (/), depending on its position, has different
150 | meanings within a file URL.
151 | 
152 | -   The // after the *file:* is part of the general syntax of
153 |     [URLs](/wiki/Uniform_resource_locator "Uniform resource locator"){.mw-redirect}.
154 |     (The double slash // should always appear in a file URL according to
155 |     the specification, but in practice many [Web
156 |     browsers](/wiki/Web_browser "Web browser") allow it to be omitted).
157 | -   The single slash between ***host*** and ***path*** is part of the
158 |     syntax of URLs.
159 | -   The slashes in ***path*** separate directory names in a hierarchical
160 |     system of directories and subdirectories. In this usage, the slash
161 |     is a general, system-independent way of separating the parts, and in
162 |     a particular host system it might be used as such in any pathname
163 |     (as in Unix systems).
164 | 
165 | <span id="Examples" class="mw-headline">Examples</span><span class="mw-editsection"><span class="mw-editsection-bracket">\[</span>[edit](/w/index.php?title=File_URI_scheme&action=edit&section=3 "Edit section: Examples")<span class="mw-editsection-bracket">\]</span></span>
166 | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
167 | 
168 | ### <span id="Unix" class="mw-headline">Unix</span><span class="mw-editsection"><span class="mw-editsection-bracket">\[</span>[edit](/w/index.php?title=File_URI_scheme&action=edit&section=4 "Edit section: Unix")<span class="mw-editsection-bracket">\]</span></span>
169 | 
170 | Here are two [Unix](/wiki/Unix "Unix") examples pointing to the same
171 | /*etc*/*fstab* file:
172 | 
173 |     file://localhost/etc/fstab
174 |     file:///etc/fstab
175 | 
176 | ### <span id="Windows" class="mw-headline">Windows</span><span class="mw-editsection"><span class="mw-editsection-bracket">\[</span>[edit](/w/index.php?title=File_URI_scheme&action=edit&section=5 "Edit section: Windows")<span class="mw-editsection-bracket">\]</span></span>
177 | 
178 | Here are some examples which may be accepted by some applications on
179 | Windows systems, referring to the same, local file
180 | *c:*\\*WINDOWS*\\*clock.avi*
181 | 
182 |     file://localhost/c|/WINDOWS/clock.avi
183 |     file:///c|/WINDOWS/clock.avi
184 |     file://localhost/c:/WINDOWS/clock.avi
185 | 
186 | Here is the URI as understood by the Windows Shell
187 | API:^[\[2\]](#cite_note-2)^
188 | 
189 |     file:///c:/WINDOWS/clock.avi
190 | 
191 | <span id="Implementations" class="mw-headline">Implementations</span><span class="mw-editsection"><span class="mw-editsection-bracket">\[</span>[edit](/w/index.php?title=File_URI_scheme&action=edit&section=6 "Edit section: Implementations")<span class="mw-editsection-bracket">\]</span></span>
192 | -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
193 | 
194 | ### <span id="Windows_2" class="mw-headline">Windows</span><span class="mw-editsection"><span class="mw-editsection-bracket">\[</span>[edit](/w/index.php?title=File_URI_scheme&action=edit&section=7 "Edit section: Windows")<span class="mw-editsection-bracket">\]</span></span>
195 | 
196 | On Microsoft Windows systems, the normal colon (:) after a device letter
197 | has sometimes been replaced by a vertical bar (|) in file URLs. This
198 | reflected the original URL syntax, which made the colon a reserved
199 | character in a path part.
200 | 
201 | Since [Internet Explorer
202 | 4](/wiki/Internet_Explorer_4 "Internet Explorer 4"), file URIs have been
203 | standardized on Windows, and should follow the following scheme. This
204 | applies to all applications which use URLMON or SHLWAPI for parsing,
205 | fetching or binding to URIs. To convert a path to a URL, use
206 | `UrlCreateFromPath`, and to convert a URL to a path, use
207 | `PathCreateFromUrl`.^[\[3\]](#cite_note-3)^
208 | 
209 | To access a file "the file.txt", the following might be used.
210 | 
211 | For a network location:
212 | 
213 |     file://hostname/path/to/the%20file.txt
214 | 
215 | Or for a local file, the hostname is omitted, but the slash is not (note
216 | the third slash):
217 | 
218 |     file:///c:/path/to/the%20file.txt
219 | 
220 | This is not the same as providing the string "localhost" or the dot "."
221 | in place of the hostname. The string "localhost" will attempt to access
222 | the file as \\\\localhost\\c:\\path\\to\\the file.txt, which will not
223 | work since the colon is not allowed in a share name. The dot "." results
224 | in the string being passed as \\\\.\\c:\\path\\to\\the file.txt, which
225 | will work for local files, but not shares on the local system. For
226 | example file://./sharename/path/to/the%20file.txt will not work, because
227 | it will result in *sharename* being interpreted as part of the
228 | DOSDEVICES namespace, not as a network share.
229 | 
230 | The following outline roughly describes the requirements.
231 | 
232 | -   The colon should be used, and should *not* be replaced with a
233 |     vertical bar for Internet Explorer.
234 | -   Forward slashes should be used to delimit paths.
235 | -   Characters such as the hash (\#) or question mark (?) which are part
236 |     of the filename should be
237 |     [percent-encoded](/wiki/Percent-encoding "Percent-encoding").
238 | -   Characters which are not allowed in URIs, but which are allowed in
239 |     filenames, must also be percent-encoded. For example, any of
240 |     "**{}\`\^** " and all control characters. In the example above, the
241 |     space in the filename is encoded as %20.
242 | -   Characters which are allowed in both URIs and filenames must NOT
243 |     be percent-encoded.
244 | -   Must not use legacy ACP encodings. (ACP code pages are specified by
245 |     DOS CHCP or Windows Control Panel language setting.)
246 | -   Unicode characters outside of the [ASCII](/wiki/ASCII "ASCII") range
247 |     must be [UTF-8](/wiki/UTF-8 "UTF-8") encoded, and those UTF-8
248 |     encodings must be percent-encoded.
249 | 
250 | Use the provided functions if possible. If must create a URL
251 | programmatically and cannot access SHLWAPI.dll (for example from script,
252 | or another programming environment where the equivalent functions are
253 | not available) the above outline will help.
254 | 
255 | #### <span id="Legacy_URLs" class="mw-headline">Legacy URLs</span><span class="mw-editsection"><span class="mw-editsection-bracket">\[</span>[edit](/w/index.php?title=File_URI_scheme&action=edit&section=8 "Edit section: Legacy URLs")<span class="mw-editsection-bracket">\]</span></span>
256 | 
257 | To aid the installed base of legacy applications on Win32
258 | `PathCreateFromUrl` recognizes certain URLs which do not meet these
259 | criteria, and treats them uniformly. These are called "legacy" file URLs
260 | as opposed to "healthy" file URLs.^[\[4\]](#cite_note-4)^
261 | 
262 | In the past, a variety of other applications have used other systems.
263 | Some added an additional two slashes. For example,
264 | \\\\remotehost\\share\\dir\\file.txt, would become
265 | file:////remotehost/share/dir/file.txt instead of the "healthy"
266 | file://remotehost/share/dir/file.txt.
267 | 
268 | ### <span id="Web_pages" class="mw-headline">Web pages</span><span class="mw-editsection"><span class="mw-editsection-bracket">\[</span>[edit](/w/index.php?title=File_URI_scheme&action=edit&section=9 "Edit section: Web pages")<span class="mw-editsection-bracket">\]</span></span>
269 | 
270 | File URLs are rarely used in [Web pages](/wiki/Web_page "Web page") on
271 | the public Internet, since they imply that a file exists on the
272 | designated host. The *host* specifier can be used to retrieve a file
273 | from an external source, although no specific file-retrieval protocol is
274 | specified; and using it should result in a message that informs the user
275 | that no mechanism to access that machine is available.
276 | 
277 | <span id="References" class="mw-headline">References</span><span class="mw-editsection"><span class="mw-editsection-bracket">\[</span>[edit](/w/index.php?title=File_URI_scheme&action=edit&section=10 "Edit section: References")<span class="mw-editsection-bracket">\]</span></span>
278 | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
279 | 
280 | <div class="reflist" style="list-style-type: decimal;">
281 | 
282 | 1.  <div id="cite_note-1">
283 | 
284 |     </div>
285 | 
286 |     <span class="mw-cite-backlink">**[\^](#cite_ref-1)**</span> <span
287 |     class="reference-text">["The file URI Scheme:
288 |     draft-ietf-appsawg-file-scheme-03"](https://tools.ietf.org/html/draft-ietf-appsawg-file-scheme-03){.external
289 |     .text}. Internet Engineering Task Force (IETF). 23 July 2015<span
290 |     class="reference-accessdate">. Retrieved <span class="nowrap">21
291 |     Aug</span> 2015</span>.<span class="Z3988"
292 |     title="ctx_ver=Z39.88-2004&amp;rfr_id=info%3Asid%2Fen.wikipedia.org%3AFile+URI+scheme&amp;rft.btitle=The+file+URI+Scheme%3A+draft-ietf-appsawg-file-scheme-03&amp;rft.date=2015-07-23&amp;rft.genre=unknown&amp;rft_id=https%3A%2F%2Ftools.ietf.org%2Fhtml%2Fdraft-ietf-appsawg-file-scheme-03&amp;rft.pub=Internet+Engineering+Task+Force+%28IETF%29&amp;rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Abook"><span
293 |     style="display:none;"> </span></span></span>
294 | 2.  <div id="cite_note-2">
295 | 
296 |     </div>
297 | 
298 |     <span class="mw-cite-backlink">**[\^](#cite_ref-2)**</span> <span
299 |     class="reference-text">Risney, Dave (2006). ["File URIs in
300 |     Windows"](http://blogs.msdn.com/b/ie/archive/2006/12/06/file-uris-in-windows.aspx){.external
301 |     .text}. *IEBlog*. Microsoft Corporation<span
302 |     class="reference-accessdate">. Retrieved <span class="nowrap">31
303 |     July</span> 2013</span>.<span class="Z3988"
304 |     title="ctx_ver=Z39.88-2004&amp;rfr_id=info%3Asid%2Fen.wikipedia.org%3AFile+URI+scheme&amp;rft.atitle=File+URIs+in+Windows&amp;rft.aufirst=Dave&amp;rft.aulast=Risney&amp;rft.date=2006&amp;rft.genre=unknown&amp;rft_id=http%3A%2F%2Fblogs.msdn.com%2Fb%2Fie%2Farchive%2F2006%2F12%2F06%2Ffile-uris-in-windows.aspx&amp;rft.jtitle=IEBlog&amp;rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Ajournal"><span
305 |     style="display:none;"> </span></span></span>
306 | 3.  <div id="cite_note-3">
307 | 
308 |     </div>
309 | 
310 |     <span class="mw-cite-backlink">**[\^](#cite_ref-3)**</span> <span
311 |     class="reference-text">[File URIs in Windows - IEBlog - Site Home -
312 |     MSDN
313 |     Blogs](http://blogs.msdn.com/ie/archive/2006/12/06/file-uris-in-windows.aspx){.external
314 |     .text}. Blogs.msdn.com (2006-12-06). Retrieved on 2014-03-08.</span>
315 | 4.  <div id="cite_note-4">
316 | 
317 |     </div>
318 | 
319 |     <span class="mw-cite-backlink">**[\^](#cite_ref-4)**</span> <span
320 |     class="reference-text">[The Bizarre and Unhappy Story of 'file:'
321 |     URLs - Free Associations - Site Home - MSDN
322 |     Blogs](http://blogs.msdn.com/freeassociations/archive/2005/05/19/420059.aspx){.external
323 |     .text}. Blogs.msdn.com (2005-05-19). Retrieved on 2014-03-08.</span>
324 | 
325 | </div>
326 | 
327 | <span id="External_links" class="mw-headline">External links</span><span class="mw-editsection"><span class="mw-editsection-bracket">\[</span>[edit](/w/index.php?title=File_URI_scheme&action=edit&section=11 "Edit section: External links")<span class="mw-editsection-bracket">\]</span></span>
328 | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
329 | 
330 | -   [File URLs](http://www.cs.tut.fi/~jkorpela/fileurl.html){.external
331 |     .text}
332 | 
333 | <div class="navbox" role="navigation"
334 | aria-labelledby="Uniform_Resource_Identifier_.28URI.29_schemes"
335 | style="padding:3px">
336 | 
337 | <div class="plainlinks hlist navbar mini">
338 | 
339 | -   [v](/wiki/Template:URI_schemes "Template:URI schemes")
340 | -   [t](/wiki/Template_talk:URI_schemes "Template talk:URI schemes")
341 | -   [e](//en.wikipedia.org/w/index.php?title=Template:URI_schemes&action=edit){.external
342 |     .text}
343 | 
344 | </div>
345 | 
346 | <div id="Uniform_Resource_Identifier_.28URI.29_schemes"
347 | style="font-size:114%">
348 | 
349 | [Uniform Resource
350 | Identifier](/wiki/Uniform_Resource_Identifier "Uniform Resource Identifier")
351 | (URI) schemes
352 | 
353 | </div>
354 | 
355 | Official
356 | <div style="padding:0em 0.25em">
357 | 
358 | -   [about](/wiki/About_URI_scheme "About URI scheme")
359 | -   [acct](/wiki/Acct_(protocol) "Acct (protocol)")
360 | -   [crid](/wiki/Content_reference_identifier "Content reference identifier")
361 | -   [data](/wiki/Data_URI_scheme "Data URI scheme")
362 | -   **file**
363 | -   [geo](/wiki/Geo_URI_scheme "Geo URI scheme")
364 | -   [http](/wiki/Hypertext_Transfer_Protocol#Technical_overview "Hypertext Transfer Protocol")
365 | -   [https](/wiki/HTTPS#Overview "HTTPS")
366 | -   [info](/wiki/Info_URI_scheme "Info URI scheme")
367 | -   [ldap](/wiki/Lightweight_Directory_Access_Protocol#URI_scheme "Lightweight Directory Access Protocol")
368 | -   [mailto](/wiki/Mailto "Mailto")
369 | -   [sip / sips](/wiki/SIP_URI_scheme "SIP URI scheme")
370 | -   [tag](/wiki/Tag_URI "Tag URI"){.mw-redirect}
371 | -   [urn](/wiki/Uniform_resource_name "Uniform resource name"){.mw-redirect}
372 | -   [view-source](/wiki/View-source_URI_scheme "View-source URI scheme")
373 | -   [ws / wss](/wiki/WebSocket#Overview "WebSocket")
374 | 
375 | </div>
376 | 
377 | Unofficial
378 | <div style="padding:0em 0.25em">
379 | 
380 | -   [coffee](/wiki/Hyper_Text_Coffee_Pot_Control_Protocol#Commands_and_replies "Hyper Text Coffee Pot Control Protocol")
381 | -   [ed2k](/wiki/Ed2k_URI_scheme "Ed2k URI scheme")
382 | -   [feed](/wiki/Feed_URI_scheme "Feed URI scheme")
383 | -   [irc / irc6 /
384 |     ircs](/wiki/Internet_Relay_Chat#URI_scheme "Internet Relay Chat")
385 | -   [ldaps](/wiki/Lightweight_Directory_Access_Protocol#URI_scheme "Lightweight Directory Access Protocol")
386 | -   [magnet](/wiki/Magnet_URI_scheme "Magnet URI scheme")
387 | -   [ymsgr](/wiki/Yahoo!_Messenger#URI_scheme "Yahoo! Messenger")
388 | 
389 | </div>
390 | 
391 | <div>
392 | 
393 | [Protocol
394 | list](/wiki/List_of_network_protocols_(OSI_model) "List of network protocols (OSI model)")
395 | 
396 | </div>
397 | 
398 | </div>
399 | 
400 | ![](//en.wikipedia.org/wiki/Special:CentralAutoLogin/start?type=1x1){width="1"
401 | height="1"}
402 | 
403 | </div>
404 | 
405 | <div class="printfooter">
406 | 
407 | Retrieved from
408 | "<https://en.wikipedia.org/w/index.php?title=File_URI_scheme&oldid=723314037>"
409 | 
410 | </div>
411 | 
412 | <div id="catlinks" class="catlinks" data-mw="interface">
413 | 
414 | <div id="mw-normal-catlinks" class="mw-normal-catlinks">
415 | 
416 | [Categories](/wiki/Help:Category "Help:Category"):
417 | -   [Internet
418 |     Standards](/wiki/Category:Internet_Standards "Category:Internet Standards")
419 | -   [Identifiers](/wiki/Category:Identifiers "Category:Identifiers")
420 | -   [URI schemes](/wiki/Category:URI_schemes "Category:URI schemes")
421 | 
422 | </div>
423 | 
424 | <div id="mw-hidden-catlinks"
425 | class="mw-hidden-catlinks mw-hidden-cats-hidden">
426 | 
427 | Hidden categories:
428 | -   [Articles needing additional references from October
429 |     2012](/wiki/Category:Articles_needing_additional_references_from_October_2012 "Category:Articles needing additional references from October 2012")
430 | -   [All articles needing additional
431 |     references](/wiki/Category:All_articles_needing_additional_references "Category:All articles needing additional references")
432 | 
433 | </div>
434 | 
435 | </div>
436 | 
437 | <div class="visualClear">
438 | 
439 | </div>
440 | 
441 | </div>
442 | 
443 | </div>
444 | 
445 | <div id="mw-navigation">
446 | 
447 | Navigation menu
448 | ---------------
449 | 
450 | <div id="mw-head">
451 | 
452 | <div id="p-personal" role="navigation"
453 | aria-labelledby="p-personal-label">
454 | 
455 | ### Personal tools {#p-personal-label}
456 | 
457 | -   <div id="pt-anonuserpage">
458 | 
459 |     </div>
460 | 
461 |     Not logged in
462 | -   <div id="pt-anontalk">
463 | 
464 |     </div>
465 | 
466 |     [Talk](/wiki/Special:MyTalk "Discussion about edits from this IP address [n]")
467 | -   <div id="pt-anoncontribs">
468 | 
469 |     </div>
470 | 
471 |     [Contributions](/wiki/Special:MyContributions "A list of edits made from this IP address [y]")
472 | -   <div id="pt-createaccount">
473 | 
474 |     </div>
475 | 
476 |     [Create
477 |     account](/w/index.php?title=Special:CreateAccount&returnto=File+URI+scheme "You are encouraged to create an account and log in; however, it is not mandatory")
478 | -   <div id="pt-login">
479 | 
480 |     </div>
481 | 
482 |     [Log
483 |     in](/w/index.php?title=Special:UserLogin&returnto=File+URI+scheme "You're encouraged to log in; however, it's not mandatory. [o]")
484 | 
485 | </div>
486 | 
487 | <div id="left-navigation">
488 | 
489 | <div id="p-namespaces" class="vectorTabs" role="navigation"
490 | aria-labelledby="p-namespaces-label">
491 | 
492 | ### Namespaces {#p-namespaces-label}
493 | 
494 | -   <div id="ca-nstab-main">
495 | 
496 |     </div>
497 | 
498 |     <span>[Article](/wiki/File_URI_scheme "View the content page [c]")</span>
499 | -   <div id="ca-talk">
500 | 
501 |     </div>
502 | 
503 |     <span>[Talk](/wiki/Talk:File_URI_scheme "Discussion about the content page [t]")</span>
504 | 
505 | </div>
506 | 
507 | <div id="p-variants" class="vectorMenu emptyPortlet" role="navigation"
508 | aria-labelledby="p-variants-label">
509 | 
510 | ### <span>Variants</span>[](#) {#p-variants-label}
511 | 
512 | <div class="menu">
513 | 
514 | </div>
515 | 
516 | </div>
517 | 
518 | </div>
519 | 
520 | <div id="right-navigation">
521 | 
522 | <div id="p-views" class="vectorTabs" role="navigation"
523 | aria-labelledby="p-views-label">
524 | 
525 | ### Views {#p-views-label}
526 | 
527 | -   <div id="ca-view">
528 | 
529 |     </div>
530 | 
531 |     <span>[Read](/wiki/File_URI_scheme)</span>
532 | -   <div id="ca-edit">
533 | 
534 |     </div>
535 | 
536 |     <span>[Edit](/w/index.php?title=File_URI_scheme&action=edit "Edit this page [e]")</span>
537 | -   <div id="ca-history">
538 | 
539 |     </div>
540 | 
541 |     <span>[View
542 |     history](/w/index.php?title=File_URI_scheme&action=history "Past revisions of this page [h]")</span>
543 | 
544 | </div>
545 | 
546 | <div id="p-cactions" class="vectorMenu emptyPortlet" role="navigation"
547 | aria-labelledby="p-cactions-label">
548 | 
549 | ### <span>More</span>[](#) {#p-cactions-label}
550 | 
551 | <div class="menu">
552 | 
553 | </div>
554 | 
555 | </div>
556 | 
557 | <div id="p-search" role="search">
558 | 
559 | ### Search
560 | 
561 | <div id="simpleSearch">
562 | 
563 | </div>
564 | 
565 | </div>
566 | 
567 | </div>
568 | 
569 | </div>
570 | 
571 | <div id="mw-panel">
572 | 
573 | <div id="p-logo" role="banner">
574 | 
575 | [](/wiki/Main_Page "Visit the main page"){.mw-wiki-logo}
576 | 
577 | </div>
578 | 
579 | <div id="p-navigation" class="portal" role="navigation"
580 | aria-labelledby="p-navigation-label">
581 | 
582 | ### Navigation {#p-navigation-label}
583 | 
584 | <div class="body">
585 | 
586 | -   <div id="n-mainpage-description">
587 | 
588 |     </div>
589 | 
590 |     [Main page](/wiki/Main_Page "Visit the main page [z]")
591 | -   <div id="n-contents">
592 | 
593 |     </div>
594 | 
595 |     [Contents](/wiki/Portal:Contents "Guides to browsing Wikipedia")
596 | -   <div id="n-featuredcontent">
597 | 
598 |     </div>
599 | 
600 |     [Featured
601 |     content](/wiki/Portal:Featured_content "Featured content – the best of Wikipedia")
602 | -   <div id="n-currentevents">
603 | 
604 |     </div>
605 | 
606 |     [Current
607 |     events](/wiki/Portal:Current_events "Find background information on current events")
608 | -   <div id="n-randompage">
609 | 
610 |     </div>
611 | 
612 |     [Random article](/wiki/Special:Random "Load a random article [x]")
613 | -   <div id="n-sitesupport">
614 | 
615 |     </div>
616 | 
617 |     [Donate to
618 |     Wikipedia](https://donate.wikimedia.org/wiki/Special:FundraiserRedirector?utm_source=donate&utm_medium=sidebar&utm_campaign=C13_en.wikipedia.org&uselang=en "Support us")
619 | -   <div id="n-shoplink">
620 | 
621 |     </div>
622 | 
623 |     [Wikipedia store](//shop.wikimedia.org "Visit the Wikipedia store")
624 | 
625 | </div>
626 | 
627 | </div>
628 | 
629 | <div id="p-interaction" class="portal" role="navigation"
630 | aria-labelledby="p-interaction-label">
631 | 
632 | ### Interaction {#p-interaction-label}
633 | 
634 | <div class="body">
635 | 
636 | -   <div id="n-help">
637 | 
638 |     </div>
639 | 
640 |     [Help](/wiki/Help:Contents "Guidance on how to use and edit Wikipedia")
641 | -   <div id="n-aboutsite">
642 | 
643 |     </div>
644 | 
645 |     [About Wikipedia](/wiki/Wikipedia:About "Find out about Wikipedia")
646 | -   <div id="n-portal">
647 | 
648 |     </div>
649 | 
650 |     [Community
651 |     portal](/wiki/Wikipedia:Community_portal "About the project, what you can do, where to find things")
652 | -   <div id="n-recentchanges">
653 | 
654 |     </div>
655 | 
656 |     [Recent
657 |     changes](/wiki/Special:RecentChanges "A list of recent changes in the wiki [r]")
658 | -   <div id="n-contactpage">
659 | 
660 |     </div>
661 | 
662 |     [Contact
663 |     page](//en.wikipedia.org/wiki/Wikipedia:Contact_us "How to contact Wikipedia")
664 | 
665 | </div>
666 | 
667 | </div>
668 | 
669 | <div id="p-tb" class="portal" role="navigation"
670 | aria-labelledby="p-tb-label">
671 | 
672 | ### Tools {#p-tb-label}
673 | 
674 | <div class="body">
675 | 
676 | -   <div id="t-whatlinkshere">
677 | 
678 |     </div>
679 | 
680 |     [What links
681 |     here](/wiki/Special:WhatLinksHere/File_URI_scheme "List of all English Wikipedia pages containing links to this page [j]")
682 | -   <div id="t-recentchangeslinked">
683 | 
684 |     </div>
685 | 
686 |     [Related
687 |     changes](/wiki/Special:RecentChangesLinked/File_URI_scheme "Recent changes in pages linked from this page [k]")
688 | -   <div id="t-upload">
689 | 
690 |     </div>
691 | 
692 |     [Upload file](/wiki/Wikipedia:File_Upload_Wizard "Upload files [u]")
693 | -   <div id="t-specialpages">
694 | 
695 |     </div>
696 | 
697 |     [Special
698 |     pages](/wiki/Special:SpecialPages "A list of all special pages [q]")
699 | -   <div id="t-permalink">
700 | 
701 |     </div>
702 | 
703 |     [Permanent
704 |     link](/w/index.php?title=File_URI_scheme&oldid=723314037 "Permanent link to this revision of the page")
705 | -   <div id="t-info">
706 | 
707 |     </div>
708 | 
709 |     [Page
710 |     information](/w/index.php?title=File_URI_scheme&action=info "More information about this page")
711 | -   <div id="t-wikibase">
712 | 
713 |     </div>
714 | 
715 |     [Wikidata
716 |     item](https://www.wikidata.org/wiki/Q5448333 "Link to connected data repository item [g]")
717 | -   <div id="t-cite">
718 | 
719 |     </div>
720 | 
721 |     [Cite this
722 |     page](/w/index.php?title=Special:CiteThisPage&page=File_URI_scheme&id=723314037 "Information on how to cite this page")
723 | 
724 | </div>
725 | 
726 | </div>
727 | 
728 | <div id="p-coll-print_export" class="portal" role="navigation"
729 | aria-labelledby="p-coll-print_export-label">
730 | 
731 | ### Print/export {#p-coll-print_export-label}
732 | 
733 | <div class="body">
734 | 
735 | -   <div id="coll-create_a_book">
736 | 
737 |     </div>
738 | 
739 |     [Create a
740 |     book](/w/index.php?title=Special:Book&bookcmd=book_creator&referer=File+URI+scheme)
741 | -   <div id="coll-download-as-rdf2latex">
742 | 
743 |     </div>
744 | 
745 |     [Download as
746 |     PDF](/w/index.php?title=Special:Book&bookcmd=render_article&arttitle=File+URI+scheme&returnto=File+URI+scheme&oldid=723314037&writer=rdf2latex)
747 | -   <div id="t-print">
748 | 
749 |     </div>
750 | 
751 |     [Printable
752 |     version](/w/index.php?title=File_URI_scheme&printable=yes "Printable version of this page [p]")
753 | 
754 | </div>
755 | 
756 | </div>
757 | 
758 | <div id="p-lang" class="portal" role="navigation"
759 | aria-labelledby="p-lang-label">
760 | 
761 | ### Languages {#p-lang-label}
762 | 
763 | <div class="body">
764 | 
765 | -   [Français](https://fr.wikipedia.org/wiki/File_URI_scheme "File URI scheme – French"){.interlanguage-link-target}
766 | -   [Русский](https://ru.wikipedia.org/wiki/File_(%D1%81%D1%85%D0%B5%D0%BC%D0%B0_URI) "File (схема URI) – Russian"){.interlanguage-link-target}
767 | -   [](#)
768 | 
769 | <div class="after-portlet after-portlet-lang">
770 | 
771 | <span class="wb-langlinks-edit wb-langlinks-link">[Edit
772 | links](https://www.wikidata.org/wiki/Q5448333#sitelinks-wikipedia "Edit interlanguage links"){.wbc-editpage}</span>
773 | 
774 | </div>
775 | 
776 | </div>
777 | 
778 | </div>
779 | 
780 | </div>
781 | 
782 | </div>
783 | 
784 | <div id="footer" role="contentinfo">
785 | 
786 | -   <div id="footer-info-lastmod">
787 | 
788 |     </div>
789 | 
790 |     This page was last modified on 2 June 2016, at 09:21.
791 | -   <div id="footer-info-copyright">
792 | 
793 |     </div>
794 | 
795 |     Text is available under the [Creative Commons Attribution-ShareAlike
796 |     License](//en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License)[](//creativecommons.org/licenses/by-sa/3.0/);
797 |     additional terms may apply. By using this site, you agree to the
798 |     [Terms of Use](//wikimediafoundation.org/wiki/Terms_of_Use) and
799 |     [Privacy Policy](//wikimediafoundation.org/wiki/Privacy_policy).
800 |     Wikipedia® is a registered trademark of the [Wikimedia
801 |     Foundation, Inc.](//www.wikimediafoundation.org/), a
802 |     non-profit organization.
803 | 
804 | <!-- -->
805 | 
806 | -   <div id="footer-places-privacy">
807 | 
808 |     </div>
809 | 
810 |     [Privacy
811 |     policy](https://wikimediafoundation.org/wiki/Privacy_policy "wmf:Privacy policy"){.extiw}
812 | -   <div id="footer-places-about">
813 | 
814 |     </div>
815 | 
816 |     [About Wikipedia](/wiki/Wikipedia:About "Wikipedia:About")
817 | -   <div id="footer-places-disclaimer">
818 | 
819 |     </div>
820 | 
821 |     [Disclaimers](/wiki/Wikipedia:General_disclaimer "Wikipedia:General disclaimer")
822 | -   <div id="footer-places-contact">
823 | 
824 |     </div>
825 | 
826 |     [Contact Wikipedia](//en.wikipedia.org/wiki/Wikipedia:Contact_us)
827 | -   <div id="footer-places-developers">
828 | 
829 |     </div>
830 | 
831 |     [Developers](https://www.mediawiki.org/wiki/Special:MyLanguage/How_to_contribute)
832 | -   <div id="footer-places-cookiestatement">
833 | 
834 |     </div>
835 | 
836 |     [Cookie
837 |     statement](https://wikimediafoundation.org/wiki/Cookie_statement)
838 | -   <div id="footer-places-mobileview">
839 | 
840 |     </div>
841 | 
842 |     [Mobile
843 |     view](//en.m.wikipedia.org/w/index.php?title=File_URI_scheme&mobileaction=toggle_view_mobile){.noprint
844 |     .stopMobileRedirectToggle}
845 | 
846 | <!-- -->
847 | 
848 | -   <div id="footer-copyrightico">
849 | 
850 |     </div>
851 | 
852 |     [![Wikimedia
853 |     Foundation](/static/images/wikimedia-button.png){width="88"
854 |     height="31"
855 |     srcset="/static/images/wikimedia-button-1.5x.png 1.5x, /static/images/wikimedia-button-2x.png 2x"}](https://wikimediafoundation.org/)
856 | -   <div id="footer-poweredbyico">
857 | 
858 |     </div>
859 | 
860 |     [![Powered by
861 |     MediaWiki](/static/images/poweredby_mediawiki_88x31.png){width="88"
862 |     height="31"
863 |     srcset="/static/images/poweredby_mediawiki_132x47.png 1.5x, /static/images/poweredby_mediawiki_176x62.png 2x"}](//www.mediawiki.org/)
864 | 
865 | <div style="clear:both">
866 | 
867 | </div>
868 | 
869 | </div>
870 | 


--------------------------------------------------------------------------------
/poetry.lock:
--------------------------------------------------------------------------------
 1 | # This file is automatically @generated by Poetry 1.8.3 and should not be changed by hand.
 2 | 
 3 | [[package]]
 4 | name = "pandocfilters"
 5 | version = "1.5.1"
 6 | description = "Utilities for writing pandoc filters in python"
 7 | optional = false
 8 | python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"
 9 | files = [
10 |     {file = "pandocfilters-1.5.1-py2.py3-none-any.whl", hash = "sha256:93be382804a9cdb0a7267585f157e5d1731bbe5545a85b268d6f5fe6232de2bc"},
11 |     {file = "pandocfilters-1.5.1.tar.gz", hash = "sha256:002b4a555ee4ebc03f8b66307e287fa492e4a77b4ea14d3f934328297bb4939e"},
12 | ]
13 | 
14 | [[package]]
15 | name = "setuptools"
16 | version = "68.0.0"
17 | description = "Easily download, build, install, upgrade, and uninstall Python packages"
18 | optional = false
19 | python-versions = ">=3.7"
20 | files = [
21 |     {file = "setuptools-68.0.0-py3-none-any.whl", hash = "sha256:11e52c67415a381d10d6b462ced9cfb97066179f0e871399e006c4ab101fc85f"},
22 |     {file = "setuptools-68.0.0.tar.gz", hash = "sha256:baf1fdb41c6da4cd2eae722e135500da913332ab3f2f5c7d33af9b492acb5235"},
23 | ]
24 | 
25 | [package.extras]
26 | docs = ["furo", "jaraco.packaging (>=9)", "jaraco.tidelift (>=1.4)", "pygments-github-lexers (==0.0.5)", "rst.linker (>=1.9)", "sphinx (>=3.5)", "sphinx-favicon", "sphinx-hoverxref (<2)", "sphinx-inline-tabs", "sphinx-lint", "sphinx-notfound-page (==0.8.3)", "sphinx-reredirects", "sphinxcontrib-towncrier"]
27 | testing = ["build[virtualenv]", "filelock (>=3.4.0)", "flake8-2020", "ini2toml[lite] (>=0.9)", "jaraco.envs (>=2.2)", "jaraco.path (>=3.2.0)", "pip (>=19.1)", "pip-run (>=8.8)", "pytest (>=6)", "pytest-black (>=0.3.7)", "pytest-checkdocs (>=2.4)", "pytest-cov", "pytest-enabler (>=1.3)", "pytest-mypy (>=0.9.1)", "pytest-perf", "pytest-ruff", "pytest-timeout", "pytest-xdist", "tomli-w (>=1.0.0)", "virtualenv (>=13.0.0)", "wheel"]
28 | testing-integration = ["build[virtualenv]", "filelock (>=3.4.0)", "jaraco.envs (>=2.2)", "jaraco.path (>=3.2.0)", "pytest", "pytest-enabler", "pytest-xdist", "tomli", "virtualenv (>=13.0.0)", "wheel"]
29 | 
30 | [metadata]
31 | lock-version = "2.0"
32 | python-versions = ">=3.7"
33 | content-hash = "ed7b5108aaa0e505021fa0a65efcc0da68f74e344ab9d0b341182ba8f73403eb"
34 | 


--------------------------------------------------------------------------------
/pypandoc/__init__.py:
--------------------------------------------------------------------------------
  1 | # -*- coding: utf-8 -*-
  2 | from __future__ import absolute_import, print_function, with_statement
  3 | from typing import Iterable
  4 | from typing import Union
  5 | from typing import Generator
  6 | 
  7 | import os
  8 | import re
  9 | import subprocess
 10 | import sys
 11 | import tempfile
 12 | import textwrap
 13 | import glob
 14 | from pathlib import Path
 15 | 
 16 | from .handler import logger, _check_log_handler
 17 | from .pandoc_download import DEFAULT_TARGET_FOLDER, download_pandoc
 18 | from .py3compat import cast_bytes, cast_unicode, string_types, url2path, urlparse
 19 | 
 20 | __author__ = u'Juho Vepsäläinen'
 21 | __author_email__ = "bebraw@gmail.com"
 22 | __maintainer__ = u'Jessica Tegner'
 23 | __url__ = 'https://github.com/JessicaTegner/pypandoc'
 24 | __version__ = '1.15'
 25 | __license__ = 'MIT'
 26 | __description__ = "Thin wrapper for pandoc."
 27 | __python_requires__ = ">=3.7"
 28 | __setup_requires__ = ['setuptools', 'pip>=8.1.0', 'wheel>=0.25.0']
 29 | __classifiers__ = [
 30 |         'Development Status :: 4 - Beta',
 31 |         'Environment :: Console',
 32 |         'Intended Audience :: Developers',
 33 |         'Intended Audience :: System Administrators',
 34 |         'License :: OSI Approved :: MIT License',
 35 |         'Operating System :: POSIX',
 36 |         'Programming Language :: Python',
 37 |         'Topic :: Text Processing',
 38 |         'Topic :: Text Processing :: Filters',
 39 |         'Programming Language :: Python :: 3',
 40 |         'Programming Language :: Python :: 3.6',
 41 |         'Programming Language :: Python :: 3.7',
 42 |         'Programming Language :: Python :: 3.8',
 43 |         'Programming Language :: Python :: 3.9',
 44 |         'Programming Language :: Python :: 3.10',
 45 |         'Programming Language :: Python :: 3.11',
 46 |         'Programming Language :: Python :: 3.12',
 47 |         'Programming Language :: Python :: Implementation :: CPython',
 48 |         'Programming Language :: Python :: Implementation :: PyPy'
 49 |     ]
 50 | 
 51 | __all__ = ['convert_file', 'convert_text',
 52 |            'get_pandoc_formats', 'get_pandoc_version', 'get_pandoc_path',
 53 |            'download_pandoc']
 54 | 
 55 | def convert_text(source:str, to:str, format:str, extra_args:Iterable=(), encoding:str='utf-8',
 56 |                  outputfile:Union[None, str, Path]=None, filters:Union[Iterable, None]=None, verify_format:bool=True,
 57 |                  sandbox:bool=False, cworkdir:Union[str, None]=None) -> str:
 58 |     """Converts given `source` from `format` to `to`.
 59 | 
 60 |     :param str source: Unicode string or bytes (see encoding)
 61 | 
 62 |     :param str to: format into which the input should be converted; can be one of
 63 |             `pypandoc.get_pandoc_formats()[1]`
 64 | 
 65 |     :param str format: the format of the inputs; can be one of `pypandoc.get_pandoc_formats()[1]`
 66 | 
 67 |     :param list extra_args: extra arguments (list of strings) to be passed to pandoc
 68 |             (Default value = ())
 69 | 
 70 |     :param str encoding: the encoding of the input bytes (Default value = 'utf-8')
 71 | 
 72 |     :param str outputfile: output will be written to outputfile or the converted content
 73 |             returned if None. The output filename can be specified as a string
 74 |             or pathlib.Path object. (Default value = None)
 75 | 
 76 |     :param list filters: pandoc filters e.g. filters=['pandoc-citeproc']
 77 | 
 78 |     :param bool verify_format: Verify from and to format before converting. Should only be set False when confident of the formats and performance is an issue.
 79 |             (Default value = True)
 80 | 
 81 |     :param bool sandbox: Run pandoc in pandocs own sandbox mode, limiting IO operations in readers and writers to reading the files specified on the command line. Anyone using pandoc on untrusted user input should use this option. Note: This only does something, on pandoc >= 2.15
 82 |             (Default value = False)
 83 | 
 84 |     :returns: converted string (unicode) or an empty string if an outputfile was given
 85 |     :rtype: unicode
 86 | 
 87 |     :raises RuntimeError: if any of the inputs are not valid of if pandoc fails with an error
 88 |     :raises OSError: if pandoc is not found; make sure it has been installed and is available at
 89 |             path.
 90 |     """
 91 |     source = _as_unicode(source, encoding)
 92 |     return _convert_input(source, format, 'string', to, extra_args=extra_args,
 93 |                           outputfile=outputfile, filters=filters,
 94 |                           verify_format=verify_format, sandbox=sandbox,
 95 |                           cworkdir=cworkdir)
 96 | 
 97 | 
 98 | def convert_file(source_file:Union[list, str, Path, Generator], to:str, format:Union[str, None]=None,
 99 |                  extra_args:Iterable=(), encoding:str='utf-8', outputfile:Union[None, str, Path]=None,
100 |                  filters:Union[Iterable, None]=None, verify_format:bool=True, sandbox:bool=False,
101 |                  cworkdir:Union[str, None]=None) -> str:
102 |     """Converts given `source` from `format` to `to`.
103 | 
104 |     :param (str, list, pathlib.Path) source_file: If a string, should be either
105 |             an absolute file path, relative file path, or a file pattern (like dir/*.md).
106 |             If a list, should be a list of file paths, file patterns, or pathlib.Path
107 |             objects. In addition, pathlib.Path objects as well as the generators produced by
108 |             pathlib.Path.glob may be specified.
109 | 
110 |     :param str to: format into which the input should be converted; can be one of
111 |             `pypandoc.get_pandoc_formats()[1]`
112 | 
113 |     :param str format: the format of the inputs; will be inferred from the source_file with an
114 |             known filename extension; can be one of `pypandoc.get_pandoc_formats()[1]`
115 |             (Default value = None)
116 | 
117 |     :param list extra_args: extra arguments (list of strings) to be passed to pandoc
118 |             (Default value = ())
119 | 
120 |     :param str encoding (deprecated): the encoding of the input bytes (Default value = 'utf-8')
121 | 
122 |     :param str outputfile: output will be written to outputfile or the converted content
123 |             returned if None. The output filename can be specified as a string
124 |             or pathlib.Path object. (Default value = None)
125 | 
126 |     :param list filters: pandoc filters e.g. filters=['pandoc-citeproc']
127 | 
128 |     :param bool verify_format: Verify from and to format before converting. Should only be set False when confident of the formats and performance is an issue.
129 |             (Default value = True)
130 | 
131 |     :param bool sandbox: Run pandoc in pandocs own sandbox mode, limiting IO operations in readers and writers to reading the files specified on the command line. Anyone using pandoc on untrusted user input should use this option. Note: This only does something, on pandoc >= 2.15
132 |             (Default value = False)
133 | 
134 |     :returns: converted string (unicode) or an empty string if an outputfile was given
135 |     :rtype: unicode
136 | 
137 |     :raises RuntimeError: if any of the inputs are not valid of if pandoc fails with an error
138 |     :raises OSError: if pandoc is not found; make sure it has been installed and is available at
139 |             path.
140 |     """
141 |     # check if we have a working directory
142 |     # if we don't, we use the current working directory
143 |     if cworkdir is None:
144 |         cworkdir = os.getcwd()
145 | 
146 |     # TODO: remove 'encoding' parameter and warning
147 |     if encoding != "utf-8":
148 |         logger.warning("The 'encoding' parameter will be removed in version 1.13. Just remove the parameter, because currently the method does not use it.")
149 | 
150 |     if _is_network_path(source_file): # if the source_file is an url
151 |         format = _identify_format_from_path(source_file, format)
152 |         return _convert_input(source_file, format, 'path', to, extra_args=extra_args,
153 |                           outputfile=outputfile, filters=filters,
154 |                           verify_format=verify_format, sandbox=sandbox,
155 |                           cworkdir=cworkdir)
156 | 
157 |     # convert the source file to a path object internally
158 |     if isinstance(source_file, str):
159 |         source_file = Path(source_file)
160 |     elif isinstance(source_file, list):
161 |         source_file = [Path(x) for x in source_file]
162 |     elif isinstance(source_file, Generator):
163 |         source_file = [Path(x) for x in source_file]
164 | 
165 | 
166 |     # we are basically interested to figure out if its an absolute path or not
167 |     # if it's not, we want to prefix the working directory
168 |     # if it's a list, we want to prefix the working directory to each item if it's not an absolute path
169 |     # if it is, just use the absolute path
170 |     if isinstance(source_file, list):
171 |         source_file = [x if x.is_absolute() else Path(cworkdir, x) for x in source_file]
172 |     elif isinstance(source_file, Generator):
173 |         source_file = (x if x.is_absolute() else Path(cworkdir, x) for x in source_file)
174 |     # check ifjust a single path was given
175 |     elif isinstance(source_file, Path):
176 |         source_file = source_file if source_file.is_absolute() else Path(cworkdir, source_file)
177 | 
178 | 
179 |     discovered_source_files = []
180 |     # if we have a list of files, we need to glob them
181 |     # if we have a single file, we need to glob it
182 |     # remember that we already converted the source_file to a path object
183 |     # so for glob.glob use both the dir and file name
184 |     if isinstance(source_file, list):
185 |         for single_source in source_file:
186 |             discovered_source_files.extend(glob.glob(str(single_source)))
187 |         if discovered_source_files == []:
188 |             discovered_source_files = source_file
189 |     else:
190 |         discovered_source_files.extend(glob.glob(str(source_file)))
191 |         if discovered_source_files == []:
192 |             discovered_source_files = [source_file]
193 | 
194 |     if not _identify_path(discovered_source_files):
195 |         raise RuntimeError("source_file is not a valid path")
196 |     format = _identify_format_from_path(discovered_source_files[0], format)
197 |     if len(discovered_source_files) == 1:
198 |         discovered_source_files = discovered_source_files[0]
199 | 
200 |     return _convert_input(discovered_source_files, format, 'path', to, extra_args=extra_args,
201 |                       outputfile=outputfile, filters=filters,
202 |                       verify_format=verify_format, sandbox=sandbox,
203 |                       cworkdir=cworkdir)
204 | 
205 | 
206 | def _identify_path(source) -> bool:
207 |     if isinstance(source, list):
208 |         for single_source in source:
209 |             if not _identify_path(single_source):
210 |                 return False
211 |         return True
212 |     is_path = False
213 |     try:
214 |         is_path = os.path.exists(source)
215 |     except UnicodeEncodeError:
216 |         is_path = os.path.exists(source.encode('utf-8'))
217 |     except:  # noqa
218 |         # still false
219 |         pass
220 | 
221 |     if not is_path:
222 |         try:
223 |             is_path = len(glob.glob(source)) >= 1
224 |         except UnicodeEncodeError:
225 |             is_path = len(glob.glob(source.encode('utf-8'))) >= 1
226 |         except:  # noqa
227 |             # still false
228 |             pass
229 |     
230 |     if not is_path:
231 |         try:
232 |             # check if it's an URL
233 |             result = urlparse(source)
234 |             if result.scheme in ["http", "https"]:
235 |                 is_path = True
236 |             elif result.scheme and result.netloc and result.path:
237 |                 # complete uri including one with a network path
238 |                 is_path = True
239 |             elif result.scheme == "file" and result.path:
240 |                 is_path = os.path.exists(url2path(source))
241 |         except AttributeError:
242 |             pass
243 | 
244 |     return is_path
245 | 
246 | def _is_network_path(source):
247 |     try:
248 |         # check if it's an URL
249 |         result = urlparse(source)
250 |         if result.scheme in ["http", "https"]:
251 |             return True
252 |         elif result.scheme and result.netloc and result.path:
253 |             # complete uri including one with a network path
254 |             return True
255 |         elif result.scheme == "file" and result.path:
256 |             return os.path.exists(url2path(source))
257 |     except AttributeError:
258 |         pass
259 |     return False
260 | 
261 | 
262 | def _identify_format_from_path(sourcefile:str, format:str) -> str:
263 |     return format or os.path.splitext(sourcefile)[1].strip('.')
264 | 
265 | 
266 | def _as_unicode(source:any, encoding:str) -> any:
267 |     if encoding != 'utf-8':
268 |         # if a source and a different encoding is given, try to decode the the source into a
269 |         # unicode string
270 |         try:
271 |             source = cast_unicode(source, encoding=encoding)
272 |         except (UnicodeDecodeError, UnicodeEncodeError):
273 |             pass
274 |     return source
275 | 
276 | 
277 | def _identify_input_type(source:any, format:str, encoding:str='utf-8'):
278 |     path = _identify_path(source)
279 |     if path:
280 |         format = _identify_format_from_path(source, format)
281 |         input_type = 'path'
282 |     else:
283 |         source = _as_unicode(source, encoding)
284 |         input_type = 'string'
285 |     return source, format, input_type
286 | 
287 | 
288 | def normalize_format(fmt):
289 |     formats = {
290 |         'dbk': 'docbook',
291 |         'md': 'markdown',
292 |         'tex': 'latex',
293 |     }
294 |     fmt = formats.get(fmt, fmt)
295 |     # rst format can have extensions
296 |     if fmt[:4] == "rest":
297 |         fmt = "rst" + fmt[4:]
298 |     return fmt
299 | 
300 | 
301 | def _validate_formats(format, to, outputfile):
302 | 
303 |     format = normalize_format(format)
304 |     to = normalize_format(to)
305 | 
306 |     if not format:
307 |         raise RuntimeError('Missing format!')
308 | 
309 |     from_formats, to_formats = get_pandoc_formats()
310 | 
311 |     if _get_base_format(format) not in from_formats:
312 |         raise RuntimeError(
313 |             'Invalid input format! Got "%s" but expected one of these: %s' % (
314 |                 _get_base_format(format), ', '.join(from_formats)))
315 | 
316 |     base_to_format = _get_base_format(to)
317 | 
318 |     file_extension = os.path.splitext(to)[1]
319 | 
320 |     if (base_to_format not in to_formats and
321 |             base_to_format != "pdf" and  # pdf is handled later # noqa: E127
322 |             file_extension != '.lua'):
323 |         raise RuntimeError(
324 |             'Invalid output format! Got %s but expected one of these: %s' % (
325 |                 base_to_format, ', '.join(to_formats)))
326 | 
327 |     # list from https://github.com/jgm/pandoc/blob/master/pandoc.hs
328 |     # `[...] where binaries = ["odt","docx","epub","epub3"] [...]`
329 |     # pdf has the same restriction
330 |     if base_to_format in ["odt", "docx", "epub", "epub3", "pdf"] and not outputfile:
331 |         raise RuntimeError(
332 |             'Output to %s only works by using a outputfile.' % base_to_format
333 |         )
334 | 
335 |     if base_to_format == "pdf":
336 |         # pdf formats needs to actually have a to format of latex and a
337 |         # filename with an ending pf .pdf
338 |         if isinstance(outputfile, str):
339 |             if outputfile[-4:] != ".pdf":
340 |                 raise RuntimeError(
341 |                     'PDF output needs an outputfile with ".pdf" as a fileending.'
342 |                 )
343 |         elif isinstance(outputfile, Path):
344 |             if outputfile.suffix != ".pdf":
345 |                 raise RuntimeError(
346 |                     'PDF output needs an outputfile with ".pdf" as a fileending.'
347 |                 )
348 |         # to is not allowed to contain pdf, but must point to latex
349 |         # it's also not allowed to contain extensions according to the docs
350 |         if to != base_to_format:
351 |             raise RuntimeError("PDF output can't contain any extensions: %s" % to)
352 |         to = "latex"
353 | 
354 |     return format, to
355 | 
356 | 
357 | def _convert_input(source, format, input_type, to, extra_args=(),
358 |                    outputfile=None, filters=None, verify_format=True,
359 |                    sandbox=False, cworkdir=None):
360 |     
361 |     _check_log_handler()
362 | 
363 |     logger.debug("Ensuring pandoc path...")
364 |     _ensure_pandoc_path()
365 | 
366 |     if verify_format:
367 |         logger.debug("Verifying format...")
368 |         format, to = _validate_formats(format, to, outputfile)
369 |     else:
370 |         format = normalize_format(format)
371 |         to = normalize_format(to)
372 | 
373 |     logger.debug("Identifying input type...")
374 |     string_input = input_type == 'string'
375 |     if not string_input:
376 |         if isinstance(source, str):
377 |             input_file = [source]
378 |         else:
379 |             input_file = source
380 |     else:
381 |         input_file = []
382 |     
383 |     input_file = sorted(input_file)
384 |     args = [__pandoc_path, '--from=' + format]
385 | 
386 |     args.append('--to=' + to)
387 | 
388 |     args += input_file
389 | 
390 |     if outputfile:
391 |         args.append("--output=" + str(outputfile))
392 | 
393 |     if sandbox:
394 |         if ensure_pandoc_minimal_version(2,15): # sandbox was introduced in pandoc 2.15, so only add if we are using 2.15 or above.
395 |             logger.debug("Adding sandbox argument...")
396 |             args.append("--sandbox")
397 |         else:
398 |             logger.warning("Sandbox argument was used, but pandoc version is too low. Ignoring argument.")
399 | 
400 |     args.extend(extra_args)
401 | 
402 |     # adds the proper filter syntax for each item in the filters list
403 |     if filters is not None:
404 |         if isinstance(filters, string_types):
405 |             filters = filters.split()
406 |         f = ['--lua-filter=' + x if x.endswith(".lua") else '--filter=' + x for x in filters]
407 |         args.extend(f)
408 | 
409 |     # To get access to pandoc-citeproc when we use a included copy of pandoc,
410 |     # we need to add the pypandoc/files dir to the PATH
411 |     new_env = os.environ.copy()
412 |     files_path = os.path.join(os.path.dirname(os.path.realpath(__file__)), "files")
413 |     new_env["PATH"] = new_env.get("PATH", "") + os.pathsep + files_path
414 |     creation_flag = 0x08000000 if sys.platform == "win32" else 0 # set creation flag to not open pandoc in new console on windows
415 | 
416 |     old_wd = os.getcwd()
417 |     if cworkdir and old_wd != cworkdir:
418 |         os.chdir(cworkdir)
419 | 
420 |     logger.debug("Running pandoc...")
421 |     p = subprocess.Popen(
422 |         args,
423 |         stdin=subprocess.PIPE if string_input else None,
424 |         stdout=subprocess.PIPE,
425 |         stderr=subprocess.PIPE,
426 |         env=new_env,
427 |         creationflags=creation_flag)
428 | 
429 |     if cworkdir is not None:
430 |         os.chdir(old_wd)
431 | 
432 |     # something else than 'None' indicates that the process already terminated
433 |     if not (p.returncode is None):
434 |         raise RuntimeError(
435 |             'Pandoc died with exitcode "%s" before receiving input: %s' % (p.returncode,
436 |                                                                            p.stderr.read())
437 |         )
438 | 
439 |     if string_input:
440 |         try:
441 |             source = cast_bytes(source, encoding='utf-8')
442 |         except (UnicodeDecodeError, UnicodeEncodeError):
443 |             # assume that it is already a utf-8 encoded string
444 |             pass
445 |     try:
446 |         stdout, stderr = p.communicate(source if string_input else None)
447 |     except OSError:
448 |         # this is happening only on Py2.6 when pandoc dies before reading all
449 |         # the input. We treat that the same as when we exit with an error...
450 |         raise RuntimeError('Pandoc died with exitcode "%s" during conversion.' % (p.returncode))
451 | 
452 |     try:
453 |         if not (to in ["odt", "docx", "epub", "epub3", "pdf"] and outputfile == "-"):
454 |             stdout = stdout.decode('utf-8')
455 |     except UnicodeDecodeError:
456 |         # this shouldn't happen: pandoc more or less guarantees that the output is utf-8!
457 |         raise RuntimeError('Pandoc output was not utf-8.')
458 |            
459 |     try:
460 |         stderr = stderr.decode('utf-8')
461 |     except UnicodeDecodeError:
462 |         # this shouldn't happen: pandoc more or less guarantees that the output is utf-8!
463 |         raise RuntimeError('Pandoc output was not utf-8.')
464 | 
465 |     # check that pandoc returned successfully
466 |     if p.returncode != 0:
467 |         raise RuntimeError(
468 |             'Pandoc died with exitcode "%s" during conversion: %s' % (p.returncode, stderr)
469 |         )
470 |     
471 |     # if there is output on stderr, process it and send to logger
472 |     if stderr:
473 |         for level, msg in _classify_pandoc_logging(stderr):
474 |             logger.log(level, msg)
475 | 
476 |     # if there is an outputfile, then stdout is likely empty!
477 |     return stdout
478 | 
479 | 
480 | def _classify_pandoc_logging(raw, default_level="WARNING"):
481 |     # Process raw and yield the contained logging levels and messages.
482 |     # Assumes that the messages are formatted like "[LEVEL] message". If the 
483 |     # first message does not have a level or any other message has a level 
484 |     # that does not conform to the pandoc standard, use the default_level 
485 |     # value instead.
486 |     
487 |     # Available pandoc logging levels adapted from:
488 |     # https://github.com/jgm/pandoc/blob/5e1249481b2e3fc27e845245a0c96c3687a23c3d/src/Text/Pandoc/Logging.hs#L44
489 |     def get_python_level(pandoc_level):
490 |         
491 |         level_map = {"ERROR": 40,
492 |                      "WARNING": 30,
493 |                      "INFO": 20,
494 |                      "DEBUG": 10}
495 |         
496 |         if pandoc_level not in level_map:
497 |             level = level_map[default_level]
498 |         else:
499 |             level = level_map[pandoc_level]
500 |         
501 |         return level
502 |     
503 |     msgs = raw.split("\n")
504 |     first = msgs.pop(0)
505 |     
506 |     search = re.search(r"\[(.*?)\]", first)
507 |     
508 |     # Use the default if the first message doesn't have a level
509 |     if search is None:
510 |         pandoc_level = default_level
511 |     else:
512 |         pandoc_level = first[search.start(1):search.end(1)]
513 |     
514 |     log_msgs = [first.replace('[{}] '.format(pandoc_level), '')]
515 |     
516 |     for msg in msgs:
517 |         
518 |         search = re.search(r"\[(.*?)\]", msg)
519 |         
520 |         if search is not None:
521 |             yield get_python_level(pandoc_level), "\n".join(log_msgs)
522 |             pandoc_level = msg[search.start(1):search.end(1)]
523 |             log_msgs = [msg.replace('[{}] '.format(pandoc_level), '')]
524 |             continue
525 |         
526 |         log_msgs.append(msg)
527 |     
528 |     yield get_python_level(pandoc_level), "\n".join(log_msgs)
529 | 
530 | 
531 | def _get_base_format(format):
532 |     '''
533 |     According to http://johnmacfarlane.net/pandoc/README.html#general-options,
534 |     syntax extensions for markdown can be individually enabled or disabled by
535 |     appending +EXTENSION or -EXTENSION to the format name.
536 |     Return the base format without any extensions.
537 |     '''
538 |     return re.split(r'\+|-', format)[0]
539 | 
540 | 
541 | def get_pandoc_formats() -> Iterable:
542 |     '''
543 |     Dynamic preprocessor for Pandoc formats.
544 |     Return 2 lists. "from_formats" and "to_formats".
545 |     '''
546 |     _ensure_pandoc_path()
547 |     creation_flag = 0x08000000 if sys.platform == "win32" else 0 # set creation flag to not open pandoc in new console on windows
548 |     p = subprocess.Popen(
549 |         [__pandoc_path, '--list-output-formats'],
550 |         stdin=subprocess.PIPE,
551 |         stderr=subprocess.PIPE,
552 |         stdout=subprocess.PIPE,
553 |         creationflags=creation_flag)
554 | 
555 |     comm = p.communicate()
556 |     out = comm[0].decode().splitlines(False)
557 |     if p.returncode != 0:
558 |         # try the old version and see if that returns something
559 |         return get_pandoc_formats_pre_1_18()
560 | 
561 |     p = subprocess.Popen(
562 |         [__pandoc_path, '--list-input-formats'],
563 |         stdin=subprocess.PIPE,
564 |         stderr=subprocess.PIPE,
565 |         stdout=subprocess.PIPE,
566 |         creationflags=creation_flag)
567 | 
568 |     comm = p.communicate()
569 |     in_ = comm[0].decode().splitlines(False)
570 | 
571 |     return [f.strip() for f in in_], [f.strip() for f in out]
572 | 
573 | 
574 | def get_pandoc_formats_pre_1_18() -> Iterable:
575 |     '''
576 |     Dynamic preprocessor for Pandoc formats for version < 1.18.
577 |     Return 2 lists. "from_formats" and "to_formats".
578 |     '''
579 |     _ensure_pandoc_path()
580 |     creation_flag = 0x08000000 if sys.platform == "win32" else 0 # set creation flag to not open pandoc in new console on windows
581 |     p = subprocess.Popen(
582 |         [__pandoc_path, '-h'],
583 |         stdin=subprocess.PIPE,
584 |         stdout=subprocess.PIPE,
585 |         creationflags=creation_flag)
586 | 
587 |     comm = p.communicate()
588 |     help_text = comm[0].decode().splitlines(False)
589 |     if p.returncode != 0 or 'Options:' not in help_text:
590 |         raise RuntimeError("Couldn't call pandoc to get output formats. Output from pandoc:\n%s" %
591 |                            str(comm))
592 |     txt = ' '.join(help_text[1:help_text.index('Options:')])
593 | 
594 |     aux = txt.split('Output formats: ')
595 |     in_ = re.sub(r'Input\sformats:\s|\*|\[.*?\]', '', aux[0]).split(',')
596 |     out = re.sub(r'\*|\[.*?\]', '', aux[1]).split(',')
597 | 
598 |     return [f.strip() for f in in_], [f.strip() for f in out]
599 | 
600 | 
601 | # copied and adapted from jupyter_nbconvert/utils/pandoc.py, Modified BSD License
602 | 
603 | def _get_pandoc_version(pandoc_path:str) -> str:
604 |     new_env = os.environ.copy()
605 |     creation_flag = 0x08000000 if sys.platform == "win32" else 0 # set creation flag to not open pandoc in new console on windows
606 |     if 'HOME' not in os.environ:
607 |         new_env['HOME'] = tempfile.gettempdir()
608 |     p = subprocess.Popen(
609 |         [pandoc_path, '--version'],
610 |         stdin=subprocess.PIPE,
611 |         stdout=subprocess.PIPE,
612 |         env=new_env,
613 |         creationflags=creation_flag)
614 |     comm = p.communicate()
615 |     out_lines = comm[0].decode().splitlines(False)
616 |     if p.returncode != 0 or len(out_lines) == 0:
617 |         raise RuntimeError("Couldn't call pandoc to get version information. Output from "
618 |                            "pandoc:\n%s" % str(comm))
619 | 
620 |     version_pattern = re.compile(r"^\d+(\.\d+){1,}$")
621 |     for tok in out_lines[0].split():
622 |         if version_pattern.match(tok):
623 |             version = tok
624 |             break
625 |     return version
626 | 
627 | 
628 | def get_pandoc_version() -> str:
629 |     """Gets the Pandoc version if Pandoc is installed.
630 | 
631 |     It will probe Pandoc for its version, cache it and return that value. If a cached version is
632 |     found, it will return the cached version and stop probing Pandoc
633 |     (unless :func:`clean_version_cache()` is called).
634 | 
635 |     :raises OSError: if pandoc is not found; make sure it has been installed and is available at
636 |             path.
637 |     """
638 |     global __version
639 | 
640 |     if __version is None:
641 |         _ensure_pandoc_path()
642 |         __version = _get_pandoc_version(__pandoc_path)
643 |     return __version
644 | 
645 | 
646 | def get_pandoc_path() -> str:
647 |     """Gets the Pandoc path if Pandoc is installed.
648 | 
649 |     It will return a path to pandoc which is used by pypandoc.
650 | 
651 |     This might be a full path or, if pandoc is on PATH, simple `pandoc`. It's guaranteed
652 |     to be callable (i.e. we could get version information from `pandoc --version`).
653 |     If `PYPANDOC_PANDOC` is set and valid, it will return that value. If the environment
654 |     variable is not set, either the full path to the included pandoc or the pandoc in
655 |     `PATH` or a pandoc in some of the more usual (platform specific) install locations
656 |     (whatever is the higher version) will be returned.
657 | 
658 |     If a cached path is found, it will return the cached path and stop probing Pandoc
659 |     (unless :func:`clean_pandocpath_cache()` is called).
660 | 
661 |     :raises OSError: if pandoc is not found
662 |     """
663 |     _ensure_pandoc_path()
664 |     return __pandoc_path
665 | 
666 | def ensure_pandoc_minimal_version(major:int, minor:int=0) -> bool:
667 |     """Check if the used pandoc fulfill a minimal version requirement.
668 | 
669 |     :param int major: pandoc major version, such as 1 or 2.
670 | 
671 |     :param int minor: pandoc minor version, such as 10 or 11.
672 | 
673 |     :returns: True if the installed pandoc is above the minimal version, False otherwise.
674 |     :rtype: bool
675 |     """
676 |     version = [int(x) for x in get_pandoc_version().split(".")]
677 |     if version[0] > int(major): # if we have pandoc2 but major is request to be 1
678 |         return True
679 |     return version[0] >= int(major) and version[1] >= int(minor)
680 |     
681 | 
682 | 
683 | def ensure_pandoc_maximal_version(major:int, minor:int=9999) -> bool:
684 |     """Check if the used pandoc fulfill a maximal version requirement.
685 | 
686 |     :param int major: pandoc major version, such as 1 or 2.
687 | 
688 |     :param int minor: pandoc minor version, such as 10 or 11.
689 | 
690 |     :returns: True if the installed pandoc is below the maximal version, False otherwise.
691 |     :rtype: bool
692 |     """
693 |     version = [int(x) for x in get_pandoc_version().split(".")]
694 |     if version[0] < int(major): # if we have pandoc1 but major is request to be 2
695 |         return True
696 |     return version[0] <= int(major) and version[1] <= int(minor)
697 | 
698 | 
699 | def _ensure_pandoc_path() -> None:
700 |     global __pandoc_path
701 |     
702 |     _check_log_handler()
703 |     
704 |     if __pandoc_path is None:
705 |         included_pandoc = os.path.join(os.path.dirname(os.path.realpath(__file__)),
706 |                                        "files", "pandoc")
707 |         search_paths = ["pandoc", included_pandoc]
708 |         pf = "linux" if sys.platform.startswith("linux") else sys.platform
709 |         try:
710 |             if pf == "win32":
711 |                 search_paths.append(os.path.join(DEFAULT_TARGET_FOLDER[pf], "pandoc.exe"))
712 |             else:
713 |                 search_paths.append(os.path.join(DEFAULT_TARGET_FOLDER[pf], "pandoc"))
714 |         except:  # noqa
715 |             # not one of the know platforms...
716 |             pass
717 |         if pf == "linux":
718 |             # Currently we install into ~/bin, but this is equally likely...
719 |             search_paths.append("~/.bin/pandoc")
720 |         # Also add the interpreter script path, as that's where pandoc could be
721 |         # installed if it's an environment and the environment wasn't activated
722 |         if pf == "win32":
723 |             search_paths.append(os.path.join(sys.exec_prefix, "Scripts", "pandoc.exe"))
724 | 
725 |             # Since this only runs on Windows, use Windows slashes
726 |             if os.getenv('ProgramFiles', None):
727 |                 search_paths.append(os.path.expandvars("${ProgramFiles}\\Pandoc\\pandoc.exe"))
728 |                 search_paths.append(os.path.expandvars("${ProgramFiles}\\Pandoc\\Pandoc.exe"))
729 |             if os.getenv('ProgramFiles(x86)', None):
730 |                 search_paths.append(os.path.expandvars("${ProgramFiles(x86)}\\Pandoc\\pandoc.exe"))
731 |                 search_paths.append(os.path.expandvars("${ProgramFiles(x86)}\\Pandoc\\Pandoc.exe"))
732 | 
733 |         # bin can also be used on windows (conda at least has it in path), so
734 |         # include it unconditionally
735 |         search_paths.append(os.path.join(sys.exec_prefix, "bin", "pandoc.exe"))
736 |         search_paths.append(os.path.join(sys.exec_prefix, "bin", "pandoc"))
737 |         # If a user added the complete path to pandoc to an env, use that as the
738 |         # only way to get pandoc so that a user can overwrite even a higher
739 |         # version in some other places.
740 |         if os.getenv('PYPANDOC_PANDOC', None):
741 |             search_paths = [os.getenv('PYPANDOC_PANDOC')]
742 |         curr_version = [0, 0, 0]
743 |         for path in search_paths:
744 |             # Needed for windows and subprocess which can't expand it on it's
745 |             # own...
746 |             path = os.path.expanduser(path)
747 |             version_string = "0.0.0"
748 |             # print("Trying: %s" % path)
749 |             try:
750 |                 version_string = _get_pandoc_version(path)
751 |             except Exception:
752 |                 # we can't use that path...
753 |                 if os.path.exists(path):
754 |                     # path exist but is not usable -> not executable?
755 |                     log_msg = ("Found {}, but not using it because of an "
756 |                                "error:".format(path))
757 |                     logger.exception(log_msg)
758 |                 continue
759 |             version = [int(x) for x in version_string.split(".")]
760 |             while len(version) < len(curr_version):
761 |                 version.append(0)
762 |             # print("%s, %s" % (path, version))
763 |             # Only use the new version if it is any bigger...
764 |             if version > curr_version:
765 |                 # print("Found: %s" % path)
766 |                 __pandoc_path = path
767 |                 curr_version = version
768 | 
769 |         if __pandoc_path is None:
770 |             # Only print hints if requested
771 |             if os.path.exists('/usr/local/bin/brew'):
772 |                 logger.info(textwrap.dedent("""\
773 |                     Maybe try:
774 | 
775 |                         brew install pandoc
776 |                 """))
777 |             elif os.path.exists('/usr/bin/apt-get'):
778 |                 logger.info(textwrap.dedent("""\
779 |                     Maybe try:
780 | 
781 |                         sudo apt-get install pandoc
782 |                 """))
783 |             elif os.path.exists('/usr/bin/yum'):
784 |                 logger.info(textwrap.dedent("""\
785 |                     Maybe try:
786 | 
787 |                     sudo yum install pandoc
788 |                 """))
789 |             logger.info(textwrap.dedent("""\
790 |                 See http://johnmacfarlane.net/pandoc/installing.html
791 |                 for installation options
792 |             """))
793 |             logger.info(textwrap.dedent("""\
794 |                 ---------------------------------------------------------------
795 | 
796 |             """))
797 |             raise OSError("No pandoc was found: either install pandoc and add it\n"
798 |                           "to your PATH or or call pypandoc.download_pandoc(...) or\n"
799 |                           "install pypandoc wheels with included pandoc.")
800 | 
801 | 
802 | def ensure_pandoc_installed(url:Union[str, None]=None, 
803 |                             targetfolder:Union[str, None]=None,
804 |                             version:str="latest",
805 |                             delete_installer:bool=False) -> None:
806 |     """Try to install pandoc if it isn't installed.
807 | 
808 |     Parameters are passed to download_pandoc()
809 | 
810 |     :raises OSError: if pandoc cannot be installed
811 |     """
812 | 
813 |     # Append targetfolder to the PATH environment variable so it is found by subprocesses
814 |     if targetfolder is not None:
815 |         os.environ["PATH"] = os.environ.get("PATH", "") + os.pathsep + os.path.abspath(os.path.expanduser(targetfolder))
816 | 
817 |     try:
818 |         _ensure_pandoc_path()
819 | 
820 |     except OSError:
821 |         download_pandoc(url=url,
822 |                         targetfolder=targetfolder,
823 |                         version=version,
824 |                         delete_installer=delete_installer)
825 | 
826 |         # Show errors in case of secondary failure
827 |         _ensure_pandoc_path()
828 | 
829 | 
830 | # -----------------------------------------------------------------------------
831 | # Internal state management
832 | # -----------------------------------------------------------------------------
833 | def clean_version_cache():
834 |     global __version
835 |     __version = None
836 | 
837 | 
838 | def clean_pandocpath_cache():
839 |     global __pandoc_path
840 |     __pandoc_path = None
841 | 
842 | 
843 | __version = None
844 | __pandoc_path = None
845 | 


--------------------------------------------------------------------------------
/pypandoc/handler.py:
--------------------------------------------------------------------------------
 1 | 
 2 | import logging
 3 | 
 4 | logger = logging.getLogger(__name__.split(".")[0])
 5 | 
 6 | 
 7 | 
 8 | def _check_log_handler():
 9 |     
10 |     # If logger has a handler do nothing
11 |     if logger.handlers: return
12 |     
13 |     # create console handler and set level to debug
14 |     ch = logging.StreamHandler()
15 |     ch.setLevel(logging.DEBUG)
16 |     
17 |     # create formatter
18 |     formatter = logging.Formatter('[%(levelname)s] %(message)s')
19 |     
20 |     # add formatter to ch
21 |     ch.setFormatter(formatter)
22 |     
23 |     # add ch to logger
24 |     logger.addHandler(ch)
25 | 


--------------------------------------------------------------------------------
/pypandoc/pandoc_download.py:
--------------------------------------------------------------------------------
  1 | # -*- coding: utf-8 -*-
  2 | import json
  3 | import os
  4 | import os.path
  5 | import platform
  6 | import re
  7 | import shutil
  8 | import subprocess
  9 | import sys
 10 | import tempfile
 11 | from typing import Union
 12 | 
 13 | import urllib
 14 | try:
 15 |     from urllib.request import urlopen, Request
 16 |     from urllib.parse import urlparse
 17 | except ImportError:
 18 |     from urllib2 import urlopen, Request
 19 |     from urlparse import urlparse
 20 | 
 21 | from .handler import logger, _check_log_handler
 22 | 
 23 | DEFAULT_TARGET_FOLDER = {
 24 |     "win32": "~\\AppData\\Local\\Pandoc",
 25 |     "linux": "~/bin",
 26 |     "darwin": "~/Applications/pandoc"
 27 | }
 28 | 
 29 | 
 30 | def _get_pandoc_urls(version="latest"):
 31 |     """Get the urls of pandoc's binaries
 32 |     Uses sys.platform keys, but removes the 2 from linux2
 33 |     Adding a new platform means implementing unpacking in "DownloadPandocCommand"
 34 |     and adding the URL here
 35 | 
 36 |     :param str version: pandoc version.
 37 |         Valid values are either a valid pandoc version e.g. "1.19.1", or "latest"
 38 |         Default: "latest".
 39 | 
 40 |     :return: str pandoc_urls: a dictionary with keys as system platform
 41 |         and values as the url pointing to respective binaries
 42 | 
 43 |     :return: str version: actual pandoc version. (e.g. "latest" will be resolved to the actual one)
 44 |     """
 45 |     # url to pandoc download page
 46 |     url = "https://api.github.com/repos/jgm/pandoc/releases/" + \
 47 |           ("tags/" if version != "latest" else "") + version
 48 |     github_token = os.getenv("GITHUB_TOKEN")
 49 |     if github_token:
 50 |         headers = {
 51 |             "Authorization": f"Bearer {github_token}"
 52 |         }
 53 |         src = Request(url, headers=headers)
 54 |     else:
 55 |         src = url
 56 |     # try to open the url
 57 |     try:
 58 |         response = urlopen(src)
 59 |     except urllib.error.HTTPError as e:
 60 |         raise RuntimeError("Invalid pandoc version {}.".format(version))
 61 |     # read json response
 62 |     data = json.loads(response.read())
 63 |     # regex for the binaries
 64 |     uname = platform.uname()[4]
 65 |     processor_architecture = (
 66 |         "arm" if uname.startswith("arm") or uname.startswith("aarch") else "amd"
 67 |     )
 68 |     regex = re.compile(
 69 |         rf"/jgm/pandoc/releases/download/.*(?:{processor_architecture}|x86|mac)"
 70 |         r".*\.(?:msi|deb|pkg)" 
 71 |     )
 72 |     # actual pandoc version
 73 |     version =  data["tag_name"]
 74 |     # dict that lookup the platform from binary extension
 75 |     ext2platform = {
 76 |         'msi': 'win32',
 77 |         'deb': 'linux',
 78 |         'pkg': 'darwin'
 79 |     }        
 80 |     # collect pandoc urls from json content
 81 |     pandoc_urls = dict()
 82 |     for asset in data["assets"]:
 83 |         download_url = asset["browser_download_url"]
 84 |         if regex.match(urlparse(download_url).path):
 85 |             pandoc_urls[ext2platform.get(asset["name"][-3:])] = download_url
 86 |     return pandoc_urls, version
 87 | 
 88 | 
 89 | def _make_executable(path):
 90 |     mode = os.stat(path).st_mode
 91 |     mode |= (mode & 0o444) >> 2  # copy R bits to X
 92 |     logger.info(f"Making {path} executable...")
 93 |     os.chmod(path, mode)
 94 | 
 95 | 
 96 | def _handle_linux(filename, targetfolder):
 97 |     logger.info(f"Unpacking {filename} to tempfolder...")
 98 | 
 99 |     tempfolder = tempfile.mkdtemp()
100 |     cur_wd = os.getcwd()
101 |     filename = os.path.abspath(filename)
102 |     try:
103 |         os.chdir(tempfolder)
104 |         cmd = ["ar", "x", filename]
105 |         # if only 3.5 is supported, should be `run(..., check=True)`
106 |         subprocess.check_call(cmd)
107 |         files = os.listdir(".")
108 |         archive_name = next(x for x in files if x.startswith('data.tar'))
109 |         cmd = ["tar", "xf", archive_name]
110 |         subprocess.check_call(cmd)
111 |         # pandoc and pandoc-citeproc are in ./usr/bin subfolder
112 |         exe = "pandoc"
113 |         src = os.path.join(tempfolder, "usr", "bin", exe)
114 |         dst = os.path.join(targetfolder, exe)
115 |         logger.info(f"Copying {exe} to {targetfolder} ...")
116 |         shutil.copyfile(src, dst)
117 |         _make_executable(dst)
118 |         exe = "pandoc-citeproc"
119 |         src = os.path.join(tempfolder, "usr", "bin", exe)
120 |         dst = os.path.join(targetfolder, exe)
121 |         if os.path.exists(src):
122 |             logger.info(f"Copying {exe} to {targetfolder} ...")
123 |             shutil.copyfile(src, dst)
124 |             _make_executable(dst)
125 |         src = os.path.join(tempfolder, "usr", "share", "doc", "pandoc", "copyright")
126 |         dst = os.path.join(targetfolder, "copyright.pandoc")
127 |         logger.info(f"Copying copyright to {targetfolder} ...")
128 |         shutil.copyfile(src, dst)
129 |     finally:
130 |         os.chdir(cur_wd)
131 |         shutil.rmtree(tempfolder)
132 | 
133 | 
134 | def _handle_darwin(filename, targetfolder):
135 |     logger.info(f"Unpacking {filename} to tempfolder...")
136 | 
137 |     tempfolder = tempfile.mkdtemp()
138 | 
139 |     pkgutilfolder = os.path.join(tempfolder, 'tmp')
140 |     cmd = ["pkgutil", "--expand", filename, pkgutilfolder]
141 |     # if only 3.5 is supported, should be `run(..., check=True)`
142 |     subprocess.check_call(cmd)
143 | 
144 |     # this will generate usr/local/bin below the dir
145 |     cmd = ["tar", "xvf", os.path.join(pkgutilfolder, "pandoc.pkg", "Payload"),
146 |            "-C", pkgutilfolder]
147 |     subprocess.check_call(cmd)
148 | 
149 |     # pandoc and pandoc-citeproc are in the ./usr/local/bin subfolder
150 | 
151 |     exe = "pandoc"
152 |     src = os.path.join(pkgutilfolder, "usr", "local", "bin", exe)
153 |     dst = os.path.join(targetfolder, exe)
154 |     logger.info(f"Copying {exe} to {targetfolder} ...")
155 |     shutil.copyfile(src, dst)
156 |     _make_executable(dst)
157 | 
158 |     exe = "pandoc-citeproc"
159 |     src = os.path.join(pkgutilfolder, "usr", "local", "bin", exe)
160 |     dst = os.path.join(targetfolder, exe)
161 |     if os.path.exists(src):
162 |         logger.info(f"Copying {exe} to {targetfolder} ...")
163 |         shutil.copyfile(src, dst)
164 |         _make_executable(dst)
165 | 
166 |     # remove temporary dir
167 |     shutil.rmtree(tempfolder)
168 |     logger.info("Done.")
169 | 
170 | 
171 | def _handle_win32(filename, targetfolder):
172 |     logger.info(f"Unpacking {filename} to tempfolder...")
173 | 
174 |     tempfolder = tempfile.mkdtemp()
175 | 
176 |     cmd = ["msiexec", "/a", filename, "/qb", "TARGETDIR=%s" % (tempfolder)]
177 |     # if only 3.5 is supported, should be `run(..., check=True)`
178 |     subprocess.check_call(cmd)
179 | 
180 |     # pandoc.exe, pandoc-citeproc.exe, and the COPYRIGHT are in the Pandoc subfolder
181 | 
182 |     exe = "pandoc.exe"
183 |     src = os.path.join(tempfolder, "Pandoc", exe)
184 |     dst = os.path.join(targetfolder, exe)
185 |     logger.info(f"Copying {exe} to {targetfolder} ...")
186 |     shutil.copyfile(src, dst)
187 | 
188 |     exe = "pandoc-citeproc.exe"
189 |     src = os.path.join(tempfolder, "Pandoc", exe)
190 |     dst = os.path.join(targetfolder, exe)
191 |     if os.path.exists(src):
192 |         logger.info(f"Copying {exe} to {targetfolder} ...")
193 |         shutil.copyfile(src, dst)
194 | 
195 |     exe = "COPYRIGHT.txt"
196 |     src = os.path.join(tempfolder, "Pandoc", exe)
197 |     dst = os.path.join(targetfolder, exe)
198 |     logger.info(f"Copying {exe} to {targetfolder} ...")
199 |     shutil.copyfile(src, dst)
200 | 
201 |     # remove temporary dir
202 |     shutil.rmtree(tempfolder)
203 |     logger.info("Done.")
204 | 
205 | 
206 | def download_pandoc(url:Union[str, None]=None,
207 |                     targetfolder:Union[str, None]=None,
208 |                     version:str="latest",
209 |                     delete_installer:bool=False,
210 |                     download_folder:Union[str, None]=None) -> None:
211 |     """Download and unpack pandoc
212 | 
213 |     Downloads prebuild binaries for pandoc from `url` and unpacks it into
214 |     `targetfolder`.
215 | 
216 |     :param str url: URL for the to be downloaded pandoc binary distribution for
217 |         the platform under which this python runs. If no `url` is give, uses
218 |         the latest available release at the time pypandoc was released.
219 | 
220 |     :param str targetfolder: directory, where the binaries should be installed
221 |         to. If no `targetfolder` is given, uses a platform specific user
222 |         location: `~/bin` on Linux, `~/Applications/pandoc` on Mac OS X, and
223 |         `~\\AppData\\Local\\Pandoc` on Windows.
224 | 
225 |     :param str download_folder: Directory, where the installer should download files before unpacking
226 |         to the target folder. If no `download_folder` is given, uses the current directory. example: `/tmp/`, `/tmp`
227 |     """
228 | 
229 |     _check_log_handler()
230 | 
231 |     pf = sys.platform
232 | 
233 |     if url is None:
234 |         # compatibility with py3
235 |         if pf.startswith("linux"):
236 |             pf = "linux"
237 |             arch = platform.architecture()[0]
238 |             if arch != "64bit":
239 |                 raise RuntimeError(f"Linux pandoc is only compiled for 64bit. Got arch={arch}.")
240 | 
241 |         # get pandoc_urls
242 |         pandoc_urls, _ = _get_pandoc_urls(version)
243 |         if pf not in pandoc_urls:
244 |             raise RuntimeError("Can't handle your platform (only Linux, Mac OS X, Windows).")
245 | 
246 |         url = pandoc_urls[pf]
247 | 
248 |     filename = url.split("/")[-1]
249 | 
250 |     if download_folder is not None:
251 |         if download_folder.endswith('/'):
252 |             download_folder = download_folder[:-1]
253 | 
254 |         filename = os.path.join(os.path.expanduser(download_folder), filename)
255 | 
256 |     if os.path.isfile(filename):
257 |         logger.info(f"Using already downloaded file {filename}")
258 |     else:
259 |         logger.info(f"Downloading pandoc from {url} ...")
260 |         # https://stackoverflow.com/questions/30627937/tracebaclk-attributeerroraddinfourl-instance-has-no-attribute-exit
261 |         response = urlopen(url)
262 |         with open(filename, 'wb') as out_file:
263 |             shutil.copyfileobj(response, out_file)
264 | 
265 |     if targetfolder is None:
266 |         targetfolder = DEFAULT_TARGET_FOLDER[pf]
267 |     targetfolder = os.path.expanduser(targetfolder)
268 | 
269 |     # Make sure target folder exists...
270 |     try:
271 |         os.makedirs(targetfolder)
272 |     except OSError:
273 |         pass  # dir already exists...
274 | 
275 |     unpack = globals().get("_handle_" + pf)
276 |     assert unpack is not None, "Can't handle download, only Linux, Windows and OS X are supported."
277 | 
278 |     unpack(filename, targetfolder)
279 |     if delete_installer:
280 |         os.remove(filename)
281 | 


--------------------------------------------------------------------------------
/pypandoc/py3compat.py:
--------------------------------------------------------------------------------
 1 | # -*- coding: utf-8 -*-
 2 | 
 3 | from __future__ import with_statement
 4 | 
 5 | import locale
 6 | import sys
 7 | 
 8 | # compat code from IPython py3compat.py and encoding.py, which is licensed under the terms of the
 9 | # Modified BSD License (also known as New or Revised or 3-Clause BSD)
10 | _DEFAULT_ENCODING = None
11 | try:
12 |     # There are reports of getpreferredencoding raising errors
13 |     # in some cases, which may well be fixed, but let's be conservative here.
14 |     _DEFAULT_ENCODING = locale.getpreferredencoding()
15 | except Exception:
16 |     pass
17 | 
18 | _DEFAULT_ENCODING = _DEFAULT_ENCODING or sys.getdefaultencoding()
19 | 
20 | 
21 | def _decode(s, encoding=None):
22 |     encoding = encoding or _DEFAULT_ENCODING
23 |     return s.decode(encoding)
24 | 
25 | 
26 | def _encode(u, encoding=None):
27 |     encoding = encoding or _DEFAULT_ENCODING
28 |     return u.encode(encoding)
29 | 
30 | 
31 | def cast_unicode(s, encoding=None):
32 |     if isinstance(s, bytes):
33 |         return _decode(s, encoding)
34 |     return s
35 | 
36 | 
37 | def cast_bytes(s, encoding=None):
38 |     # bytes == str on py2.7 -> always encode on py2
39 |     if not isinstance(s, bytes):
40 |         return _encode(s, encoding)
41 |     return s
42 | 
43 | 
44 | if sys.version_info[0] >= 3:
45 |     PY3 = True
46 | 
47 |     string_types = (str,)
48 |     unicode_type = str
49 | 
50 |     # from http://stackoverflow.com/questions/11687478/convert-a-filename-to-a-file-url
51 |     from urllib.parse import urljoin, urlparse
52 |     from urllib.request import pathname2url, url2pathname
53 | 
54 | 
55 |     def path2url(path):  # noqa: E303
56 |         return urljoin('file:', pathname2url(path))
57 | 
58 | 
59 |     def url2path(url):  # noqa: E303
60 |         return url2pathname(urlparse(url).path)
61 | 
62 | else:
63 |     PY3 = False
64 | 
65 |     string_types = (str, unicode)  # noqa: F821
66 |     unicode_type = unicode  # noqa: F821
67 | 
68 |     from urlparse import urljoin, urlparse
69 |     import urllib
70 | 
71 | 
72 |     def path2url(path):  # noqa: E303
73 |         return urljoin('file:', urllib.pathname2url(path))
74 | 
75 | 
76 |     def url2path(url):  # noqa: E303
77 |         return urllib.url2pathname(urlparse(url).path)
78 | 


--------------------------------------------------------------------------------
/pyproject.toml:
--------------------------------------------------------------------------------
 1 | [tool.poetry]
 2 | name = "pypandoc"
 3 | version = "1.15"
 4 | description = "Thin wrapper for pandoc"
 5 | authors = ["JessicaTegner <jessica.tegneroutlook.com>"]
 6 | license = "MIT"
 7 | readme = "README.md"
 8 | repository = "https://github.com/JessicaTegner/pypandoc"
 9 | 
10 | classifiers = [
11 |         'Development Status :: 4 - Beta',
12 |         'Environment :: Console',
13 |         'Intended Audience :: Developers',
14 |         'Intended Audience :: System Administrators',
15 |         'Operating System :: POSIX',
16 |         'Programming Language :: Python',
17 |         'Topic :: Text Processing',
18 |         'Topic :: Text Processing :: Filters',
19 |         'Programming Language :: Python :: 3',
20 |         'Programming Language :: Python :: 3.6',
21 |         'Programming Language :: Python :: 3.7',
22 |         'Programming Language :: Python :: 3.8',
23 |         'Programming Language :: Python :: 3.9',
24 |         'Programming Language :: Python :: 3.10',
25 |         'Programming Language :: Python :: 3.11',
26 |         'Programming Language :: Python :: 3.12',
27 |         'Programming Language :: Python :: Implementation :: CPython',
28 |         'Programming Language :: Python :: Implementation :: PyPy'
29 |     ]
30 | 
31 | packages = [
32 |     { include = "pypandoc" },
33 | ]
34 | 
35 | [tool.poetry.dependencies]
36 | python = ">=3.7"
37 | 
38 | [tool.poetry.dev-dependencies]
39 | pandocfilters = "^1.5"
40 | setuptools = "68"
41 | 
42 | [tool.poetry.group.dev.dependencies]
43 | pandocfilters = "^1.5"
44 | setuptools = "68"
45 | 
46 | [build-system]
47 | requires = ["poetry-core>=1.0.0"]
48 | build-backend = "poetry.core.masonry.api"
49 | 
50 | [tool.poetry.urls]
51 | "Issue Tracker" = "https://github.com/JessicaTegner/pypandoc/issues"
52 | 
53 | 


--------------------------------------------------------------------------------
/release.md:
--------------------------------------------------------------------------------
 1 | # Making a release
 2 | 
 3 | This is the internal checklist, so that @janschulz doesn't have to do another brown paper bag force-pushing the tags...
 4 | 
 5 | - checkout `git fetch origin && git checkout origin/master`
 6 | - run the tests (on windows): `python tests.py` -> everything ok?
 7 | - increment the version in `pypandoc/__init__.py` and `pyproject.toml`, commit with `git commit -m "pypandoc vx.x.x"`
 8 | - tag the version: `git tag -a vx.x.x`, write a nice version message summarizing new features
 9 | - push directly to the repo: `git push; git push --tags`
10 | - celebrate :-)


--------------------------------------------------------------------------------
/setup.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | # -*- coding: utf-8 -*-
 3 | import pypandoc
 4 | import io
 5 | from setuptools import setup
 6 | 
 7 | with io.open('README.md', encoding="utf-8") as f:
 8 |     long_description = f.read()
 9 | 
10 | module = pypandoc
11 | setup(
12 |     name = 'pypandoc',
13 |     version = module.__version__,
14 |     url = pypandoc.__url__,
15 |     license = pypandoc.__license__,
16 |     description = pypandoc.__description__,
17 |     long_description = long_description,
18 |     long_description_content_type='text/markdown',
19 |     author = module.__author__.encode('utf8'),
20 |     author_email = pypandoc.__author_email__,
21 |     packages = ['pypandoc'],
22 |     python_requires=pypandoc.__python_requires__,
23 |     setup_requires = pypandoc.__setup_requires__,
24 |     classifiers=pypandoc.__classifiers__,
25 |     test_suite = 'tests',
26 |     project_urls={
27 |         'Source': pypandoc.__url__,
28 |         'Tracker': pypandoc.__url__ + '/issues',
29 |     }
30 | )
31 | 


--------------------------------------------------------------------------------
/setup_binary.py:
--------------------------------------------------------------------------------
  1 | #!/usr/bin/env python
  2 | # -*- coding: utf-8 -*-
  3 | import pypandoc
  4 | from setuptools import setup, Command
  5 | 
  6 | import sys
  7 | import os
  8 | import os.path
  9 | import io
 10 | 
 11 | try:
 12 |     from urllib.request import urlopen
 13 | except ImportError:
 14 |     from urllib import urlopen
 15 | 
 16 | 
 17 | with io.open('README.md', encoding="utf-8") as f:
 18 |     long_description = f.read()
 19 | 
 20 | 
 21 | 
 22 | class DownloadPandocCommand(Command):
 23 | 
 24 |     """Download pandoc"""
 25 | 
 26 |     description = "downloads a pandoc release and adds it to the package"
 27 |     user_options = []
 28 | 
 29 |     def initialize_options(self):
 30 |         pass
 31 | 
 32 |     def finalize_options(self):
 33 |         pass
 34 | 
 35 |     def run(self):
 36 |         from pypandoc.pandoc_download import download_pandoc
 37 |         targetfolder = os.path.join(os.path.dirname(os.path.realpath(__file__)), "pypandoc", "files")
 38 |         download_pandoc(targetfolder=targetfolder)
 39 | 
 40 | 
 41 | cmd_classes = {'download_pandoc': DownloadPandocCommand}
 42 | 
 43 | # Make sure wheels end up platform specific, if they include a pandoc binary
 44 | has_pandoc = (os.path.isfile(os.path.join("pypandoc", "files", "pandoc")) or
 45 |               os.path.isfile(os.path.join("pypandoc", "files", "pandoc.exe")))
 46 | is_build_wheel = ("bdist_wheel" in sys.argv)
 47 | is_download_pandoc = ("download_pandoc" in sys.argv)
 48 | 
 49 | if is_build_wheel:
 50 |     if has_pandoc or is_download_pandoc:
 51 |         # we need to make sure that bdist_wheel is after is_download_pandoc,
 52 |         # otherwise we don't include pandoc in the wheel... :-(
 53 |         pos_bdist_wheel = sys.argv.index("bdist_wheel")
 54 |         if is_download_pandoc:
 55 |             pos_download_pandoc = sys.argv.index("download_pandoc")
 56 |             if pos_bdist_wheel < pos_download_pandoc:
 57 |                 raise RuntimeError("'download_pandoc' needs to be before 'bdist_wheel'.")
 58 |         # we also need to make sure that this version of bdist_wheel supports
 59 |         # the --plat-name argument
 60 |         try:
 61 |             import wheel
 62 |             from distutils.version import StrictVersion
 63 |             if not StrictVersion(wheel.__version__) >= StrictVersion("0.27"):
 64 |                 msg = "Including pandoc in wheel needs wheel >=0.27 but found %s.\nPlease update wheel!"
 65 |                 raise RuntimeError(msg % wheel.__version__)
 66 |         except ImportError:
 67 |             # the real error will happen further down...
 68 |             print("No wheel installed, please install 'wheel'...")
 69 |         print("forcing platform specific wheel name...")
 70 |         from distutils.util import get_platform
 71 |         sys.argv.insert(pos_bdist_wheel + 1, '--plat-name')
 72 |         sys.argv.insert(pos_bdist_wheel + 2, get_platform())
 73 |     else:
 74 |         print("no pandoc found, building platform unspecific wheel...")
 75 |         print("use 'python setup.py download_pandoc' to download pandoc.")
 76 | 
 77 | module = pypandoc
 78 | setup(
 79 |     name = 'pypandoc_binary',
 80 |     version = module.__version__,
 81 |     url = pypandoc.__url__,
 82 |     license = pypandoc.__license__,
 83 |     description = pypandoc.__description__,
 84 |     long_description = long_description,
 85 |     long_description_content_type='text/markdown',
 86 |     author = module.__author__.encode('utf8'),
 87 |     author_email = pypandoc.__author_email__,
 88 |     packages = ['pypandoc'],
 89 |     package_data={'pypandoc': ['files/*']},
 90 |     python_requires=pypandoc.__python_requires__,
 91 |     setup_requires = pypandoc.__setup_requires__,
 92 |     classifiers=pypandoc.__classifiers__,
 93 |     test_suite = 'tests',
 94 |     cmdclass=cmd_classes,
 95 |     project_urls={
 96 |         'Source': pypandoc.__url__,
 97 |         'Tracker': pypandoc.__url__ + '/issues',
 98 |     }
 99 | )
100 | 


--------------------------------------------------------------------------------
/tea.yaml:
--------------------------------------------------------------------------------
1 | # https://tea.xyz/what-is-this-file
2 | ---
3 | version: 1.0.0
4 | codeOwners:
5 |   - '0xa59BcDA45A60dACA0Ee6FD893B03C2C9B27a6a95'
6 | quorum: 1
7 | 


--------------------------------------------------------------------------------
/test.md:
--------------------------------------------------------------------------------
1 | "# headline" 
2 | 


--------------------------------------------------------------------------------
/test_data/index.html:
--------------------------------------------------------------------------------
 1 | <!DOCTYPE html>
 2 | <html lang="en">
 3 | 
 4 | <head>
 5 |   <title>Test Title</title>
 6 |   <meta name="viewport" content="width=device-width, initial-scale=1">
 7 | 
 8 | <body>
 9 | 
10 |   <h1 class="section">Test Heading</h1>
11 | 
12 |   <div class="row">
13 |     <img src="test.png" alt="test alt" />
14 |   </div>
15 | 
16 | </body>
17 | 
18 | </html>


--------------------------------------------------------------------------------
/test_data/test.docx:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/nstrmx/pypandoc/197a95c1ec92e59d795a05abe096141a381d0e5b/test_data/test.docx


--------------------------------------------------------------------------------
/test_data/test.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/nstrmx/pypandoc/197a95c1ec92e59d795a05abe096141a381d0e5b/test_data/test.png


--------------------------------------------------------------------------------
/tests.py:
--------------------------------------------------------------------------------
  1 | #!/usr/bin/env python
  2 | # -*- coding: utf-8 -*-
  3 | 
  4 | import contextlib
  5 | import io
  6 | import logging
  7 | import os
  8 | import re
  9 | import shutil
 10 | import subprocess
 11 | import sys
 12 | import tempfile
 13 | import textwrap
 14 | import unittest
 15 | import warnings
 16 | from pathlib import Path
 17 | 
 18 | import pypandoc
 19 | from pypandoc.py3compat import path2url, string_types, unicode_type
 20 | 
 21 | 
 22 | @contextlib.contextmanager
 23 | def capture(command, *args, **kwargs):
 24 |   err, sys.stderr = sys.stderr, io.StringIO()
 25 |   try:
 26 |     command(*args, **kwargs)
 27 |     sys.stderr.seek(0)
 28 |     yield sys.stderr.read()
 29 |   finally:
 30 |     sys.stderr = err
 31 | 
 32 | 
 33 | @contextlib.contextmanager
 34 | def closed_tempfile(suffix, text=None, dir_name=None):
 35 |     file_name = None
 36 |     try:
 37 |         if dir_name:
 38 |             dir_name = tempfile.mkdtemp(suffix=dir_name)
 39 | 
 40 |         with tempfile.NamedTemporaryFile('w+t', suffix=suffix, delete=False, dir=dir_name) as test_file:
 41 |             file_name = test_file.name
 42 |             if text:
 43 |                 test_file.write(text)
 44 |                 test_file.flush()
 45 |         yield file_name
 46 |     finally:
 47 |         if dir_name:
 48 |             shutil.rmtree(dir_name, ignore_errors=True)
 49 |         elif file_name:
 50 |             os.remove(file_name)
 51 | 
 52 | 
 53 | # Stolen from pandas
 54 | def is_list_like(arg):
 55 |     return (hasattr(arg, '__iter__') and
 56 |             not isinstance(arg, string_types))
 57 | 
 58 | 
 59 | @contextlib.contextmanager
 60 | def assert_produces_warning(expected_warning=Warning, filter_level="always",
 61 |                             clear=None, check_stacklevel=True):
 62 |     """
 63 |     Context manager for running code that expects to raise (or not raise)
 64 |     warnings.  Checks that code raises the expected warning and only the
 65 |     expected warning. Pass ``False`` or ``None`` to check that it does *not*
 66 |     raise a warning. Defaults to ``exception.Warning``, baseclass of all
 67 |     Warnings. (basically a wrapper around ``warnings.catch_warnings``).
 68 |     >>> import warnings
 69 |     >>> with assert_produces_warning():
 70 |     ...     warnings.warn(UserWarning())
 71 |     ...
 72 |     >>> with assert_produces_warning(False):
 73 |     ...     warnings.warn(RuntimeWarning())
 74 |     ...
 75 |     Traceback (most recent call last):
 76 |         ...
 77 |     AssertionError: Caused unexpected warning(s): ['RuntimeWarning'].
 78 |     >>> with assert_produces_warning(UserWarning):
 79 |     ...     warnings.warn(RuntimeWarning())
 80 |     Traceback (most recent call last):
 81 |         ...
 82 |     AssertionError: Did not see expected warning of class 'UserWarning'.
 83 |     ..warn:: This is *not* thread-safe.
 84 |     """
 85 |     with warnings.catch_warnings(record=True) as w:
 86 | 
 87 |         if clear is not None:
 88 |             # make sure that we are clearing these warnings
 89 |             # if they have happened before
 90 |             # to guarantee that we will catch them
 91 |             if not is_list_like(clear):
 92 |                 clear = [clear]
 93 |             for m in clear:
 94 |                 try:
 95 |                     m.__warningregistry__.clear()
 96 |                 except Exception as e:
 97 |                     # ignore...
 98 |                     print(str(e))
 99 | 
100 |         saw_warning = False
101 |         warnings.simplefilter(filter_level)
102 |         yield w
103 |         extra_warnings = []
104 | 
105 |         for actual_warning in w:
106 |             if (expected_warning and issubclass(actual_warning.category,
107 |                                                 expected_warning)):
108 |                 saw_warning = True
109 | 
110 |                 if check_stacklevel and issubclass(actual_warning.category,
111 |                                                    (FutureWarning,
112 |                                                     DeprecationWarning)):
113 |                     from inspect import getframeinfo, stack
114 |                     caller = getframeinfo(stack()[2][0])
115 |                     msg = (("Warning not set with correct stacklevel. " +
116 |                             "File where warning is raised: {0} != {1}. " +
117 |                             "Warning message: {2}").format(
118 |                         actual_warning.filename, caller.filename,
119 |                         actual_warning.message))
120 |                     assert actual_warning.filename == caller.filename, msg
121 |             else:
122 |                 extra_warnings.append(actual_warning.category.__name__)
123 |         if expected_warning:
124 |             assert saw_warning, ("Did not see expected warning of class %r."
125 |                                  % expected_warning.__name__)
126 |         assert not extra_warnings, ("Caused unexpected warning(s): %r."
127 |                                     % extra_warnings)
128 | 
129 | 
130 | class TestPypandoc(unittest.TestCase):
131 | 
132 |     # Python 2 compatibility
133 |     if not hasattr(unittest.TestCase, 'assertRaisesRegex'):
134 |         assertRaisesRegex = unittest.TestCase.assertRaisesRegexp
135 | 
136 |     def setUp(self):
137 |         if 'HOME' not in os.environ:
138 |             # if this is used with older versions of pandoc-citeproc
139 |             # https://github.com/jgm/pandoc-citeproc/issues/35
140 |             if 'TRAVIS_BUILD_DIR' in os.environ:
141 |                 os.environ["HOME"] = os.environ["TRAVIS_BUILD_DIR"]
142 |                 print("Using TRAVIS_BUILD_DIR as HOME")
143 |             else:
144 |                 os.environ["HOME"] = str(os.getcwd())
145 |                 print("Using current dir as HOME")
146 |         print(os.environ["HOME"])
147 | 
148 |     def test_get_pandoc_formats(self):
149 |         inputs, outputs = pypandoc.get_pandoc_formats()
150 |         self.assertTrue("markdown" in inputs)
151 |         self.assertTrue("json" in inputs)
152 |         self.assertTrue("twiki" in inputs)
153 |         self.assertTrue("markdown" in outputs)
154 | 
155 |     def test_get_pandoc_version(self):
156 |         assert "HOME" in os.environ, "No HOME set, this will error..."
157 |         version = pypandoc.get_pandoc_version()
158 |         self.assertTrue(isinstance(version, pypandoc.string_types))
159 |         major = int(version.split(".")[0])
160 |         self.assertTrue(major in [0, 1, 2, 3])
161 | 
162 |     def test_ensure_pandoc_minimal_version(self):
163 |         assert "HOME" in os.environ, "No HOME set, this will error..."
164 |         assert pypandoc.ensure_pandoc_minimal_version(1) == True
165 |         assert pypandoc.ensure_pandoc_minimal_version(1,1) == True
166 |         assert pypandoc.ensure_pandoc_minimal_version(999,999) == False
167 | 
168 |     def test_ensure_pandoc_maximal_version(self):
169 |         assert "HOME" in os.environ, "No HOME set, this will error..."
170 |         assert pypandoc.ensure_pandoc_maximal_version(999) == True
171 |         assert pypandoc.ensure_pandoc_maximal_version(999,999) == True
172 |         assert pypandoc.ensure_pandoc_maximal_version(1,1) == False
173 | 
174 |     def test_converts_valid_format(self):
175 |         self.assertEqualExceptForNewlineEnd(pypandoc.convert_text("ok", format='md', to='rest'), 'ok')
176 | 
177 |     def test_does_not_convert_to_invalid_format(self):
178 |         def f():
179 |             pypandoc.convert_text("ok", format='md', to='invalid')
180 | 
181 |         with self.assertRaisesRegex(RuntimeError, "Invalid output format! Got invalid but "):
182 |             f()
183 | 
184 |     def test_does_not_convert_from_invalid_format(self):
185 |         def f():
186 |             pypandoc.convert_text("ok", format='invalid', to='rest')
187 | 
188 |         with self.assertRaisesRegex(RuntimeError, 'Invalid input format! Got "invalid" but '):
189 |             f()
190 | 
191 |     def test_basic_conversion_from_file(self):
192 |         with closed_tempfile('.md', text='# some title\n') as file_name:
193 |             expected = u'some title{0}=========={0}{0}'.format(os.linesep)
194 |             received = pypandoc.convert_file(file_name, 'rst')
195 |             self.assertEqualExceptForNewlineEnd(expected, received)
196 | 
197 |     def test_basic_conversion_from_multiple_files(self):
198 |         with closed_tempfile('.md', text='some title') as file_name1:
199 |             with closed_tempfile('.md', text='some title') as file_name2:
200 |                 expected = '<p>some title</p>\n<p>some title</p>'
201 |                 received = pypandoc.convert_file([file_name1,file_name2], 'html')
202 |                 self.assertEqualExceptForNewlineEnd(expected, received)
203 | 
204 |     def test_basic_conversion_from_file_pattern(self):
205 |         received = pypandoc.convert_file("./*.md", 'html')
206 |         received = received.lower()
207 |         assert "making a release" in received
208 |         assert "pypandoc provides a thin wrapper" in received
209 | 
210 |     def test_basic_conversion_from_file_pattern_with_input_list(self):
211 |         received = pypandoc.convert_file(["./*.md", "./*.md"], 'html')
212 |         received = received.lower()
213 |         assert "making a release" in received
214 |         assert "pypandoc provides a thin wrapper" in received
215 | 
216 |     @unittest.skipIf(sys.platform.startswith("win"), "File based urls do not work on windows: "
217 |                                                      "https://github.com/jgm/pandoc/issues/4613")
218 |     def test_basic_conversion_from_file_url(self):
219 |         with closed_tempfile('.md', text='# some title\n') as file_name:
220 |             expected = u'some title{0}=========={0}{0}'.format(os.linesep)
221 |             # this keeps the : (which should be '|' on windows but pandoc
222 |             # doesn't like it
223 |             file_url = path2url(file_name)
224 |             assert pypandoc._identify_path(file_url)
225 | 
226 |             received = pypandoc.convert_file(file_url, 'rst')
227 |             self.assertEqualExceptForNewlineEnd(expected, received)
228 | 
229 |     def test_basic_conversion_from_http_url(self):
230 |         url = 'https://raw.githubusercontent.com/bebraw/pypandoc/master/README.md'
231 |         received = pypandoc.convert_file(url, 'html')
232 |         assert "GPL2 license" in received
233 | 
234 |     def test_conversion_with_data_files(self):
235 |         # remove our test.docx file from our test_data dir if it already exosts
236 |         test_data_dir = os.path.join(os.path.dirname(__file__), 'test_data')
237 |         test_docx_file = os.path.join(test_data_dir, 'test.docx')
238 |         if os.path.exists(test_docx_file):
239 |             os.remove(test_docx_file)
240 |         result = pypandoc.convert_file(
241 |           os.path.join(test_data_dir, 'index.html'),
242 |           to='docx',
243 |           format='html',
244 |           outputfile=test_docx_file,
245 |           sandbox=True,
246 |         )
247 |         print(result)
248 | 
249 |     def test_convert_with_custom_writer(self):
250 |         version = pypandoc.get_pandoc_version()
251 |         major = int(version.split(".")[0])
252 |         if major == 3:
253 |             # apparently --print-default-data-file fails on pandoc3x
254 |             return
255 |         lua_file_content = self.create_sample_lua()
256 |         with closed_tempfile('.md', text='# title\n') as file_name:
257 |             with closed_tempfile('.lua', text=lua_file_content, dir_name="foo-bar+baz") as lua_file_name:
258 |                 expected = u'<h1 id="title">title</h1>{0}'.format(os.linesep)
259 |                 received = pypandoc.convert_file(file_name, lua_file_name)
260 |                 self.assertEqualExceptForNewlineEnd(expected, received)
261 | 
262 |     def test_basic_conversion_from_file_with_format(self):
263 |         with closed_tempfile('.md', text='# some title\n') as file_name:
264 |             expected = u'some title{0}=========={0}{0}'.format(os.linesep)
265 |             received = pypandoc.convert_file(file_name, 'rst', format='md')
266 |             self.assertEqualExceptForNewlineEnd(expected, received)
267 | 
268 |             received = pypandoc.convert_file(file_name, 'rst', format='md')
269 |             self.assertEqualExceptForNewlineEnd(expected, received)
270 | 
271 |     def test_basic_conversion_from_string(self):
272 |         expected = u'some title{0}=========={0}{0}'.format(os.linesep)
273 |         received = pypandoc.convert_text('# some title', 'rst', format='md')
274 |         self.assertEqualExceptForNewlineEnd(expected, received)
275 | 
276 |         expected = u'some title{0}=========={0}{0}'.format(os.linesep)
277 |         received = pypandoc.convert_text('# some title', 'rst', format='md')
278 |         self.assertEqualExceptForNewlineEnd(expected, received)
279 | 
280 |     def test_conversion_with_markdown_extensions(self):
281 |         input = '<s>strike</s>'
282 |         expected_with_extension = u'~~strike~~'
283 |         expected_without_extension = u'<s>strike</s>'
284 |         received_with_extension = pypandoc.convert_text(input, 'markdown+strikeout',
285 |                                                    format='html')
286 |         received_without_extension = pypandoc.convert_text(input,
287 |                                                       'markdown-strikeout',
288 |                                                       format='html')
289 |         self.assertEqualExceptForNewlineEnd(expected_with_extension, received_with_extension)
290 |         self.assertEqualExceptForNewlineEnd(expected_without_extension, received_without_extension)
291 | 
292 |     def test_conversion_from_markdown_with_extensions(self):
293 |         # Apparently without the extension, ~~ gets turned into different code
294 |         # depending on the pandoc version. So we do not test for that anymore...
295 |         input = u'~~strike~~'
296 |         expected_with_extension = u'<p><del>strike</del></p>'
297 |         received_with_extension = pypandoc.convert_text(input, 'html', format=u'markdown+strikeout')
298 |         self.assertEqualExceptForNewlineEnd(expected_with_extension, received_with_extension)
299 | 
300 |     def test_basic_conversion_to_file(self):
301 |         with closed_tempfile('.rst', ) as file_name:
302 |             expected = u'some title{0}=========={0}{0}'.format(os.linesep)
303 |             received = pypandoc.convert_text('# some title\n', to='rst', format='md', outputfile=file_name)
304 |             self.assertEqualExceptForNewlineEnd("", received)
305 |             with io.open(file_name) as f:
306 |                 written = f.read()
307 |             self.assertEqualExceptForNewlineEnd(expected, written)
308 | 
309 |         # to odf does not work without a file
310 |         def f():
311 |             pypandoc.convert_text('# some title\n', to='odf', format='md',
312 |                              outputfile=None)
313 | 
314 |         with self.assertRaisesRegex(RuntimeError, "Invalid output format! Got odf but "):
315 |             f()
316 | 
317 |     def test_conversion_with_empty_filter(self):
318 |         # we just want to get a temp file name, where we can write to
319 |         filters = ''
320 |         written = pypandoc.convert_file('./filter_test.md', to='html', format='md',
321 |                                    outputfile=None, filters=filters)
322 |         import re as re
323 |         # This should not use the pandoc-citeproc module and will not find the
324 |         # strings
325 |         found = re.search(r'Fenner', written)
326 |         self.assertTrue(found is None)
327 |         found = re.search(r'10.1038', written)
328 |         self.assertTrue(found is None)
329 | 
330 |     def test_conversion_with_python_filter(self):
331 |         markdown_source = "**Here comes the content.**"
332 |         python_source = '''\
333 |         #!{0}
334 | 
335 |         """
336 |         Pandoc filter to convert all regular text to uppercase.
337 |         Code, link URLs, etc. are not affected.
338 |         """
339 | 
340 |         from pandocfilters import toJSONFilter, Str
341 | 
342 |         def caps(key, value, format, meta):
343 |             if key == 'Str':
344 |                 return Str(value.upper())
345 | 
346 |         if __name__ == "__main__":
347 |             toJSONFilter(caps)
348 |         '''
349 |         python_source = textwrap.dedent(python_source)
350 |         python_source = python_source.format(sys.executable)
351 |         
352 |         with closed_tempfile(".py", python_source) as tempfile:
353 |             os.chmod(tempfile, 0o755)
354 |             output = pypandoc.convert_text(
355 |                 markdown_source, to='html', format='md', outputfile=None, filters=tempfile
356 |             ).strip()
357 |             expected = '<p><strong>HERE COMES THE CONTENT.</strong></p>'
358 |             self.assertTrue(output == expected)
359 | 
360 |     def test_conversion_with_lua_filter(self):
361 |         markdown_source = "**Here comes the content.**"
362 |         lua_source = """\
363 |         -- taken from: https://pandoc.org/lua-filters.html
364 |         function Strong(elem)
365 |             return pandoc.SmallCaps(elem.c)
366 |         end
367 |         """
368 |         lua_source = textwrap.dedent(lua_source)
369 |         with closed_tempfile(".lua", lua_source) as tempfile:
370 |             output = pypandoc.convert_text(
371 |                 markdown_source, to='html', format='md', outputfile=None, filters=tempfile
372 |             ).strip()
373 |             expected = '<p><span class="smallcaps">Here comes the content.</span></p>'
374 |             self.assertTrue(output == expected)
375 | 
376 |     def test_conversion_with_mixed_filters(self):
377 |         markdown_source = "-0-"
378 | 
379 |         lua = """\
380 |         function Para(elem)
381 |             return pandoc.Para(elem.content .. {{"{0}-"}})
382 |         end
383 |         """
384 |         lua = textwrap.dedent(lua)
385 | 
386 |         python = """\
387 |         #!{0}
388 | 
389 |         from pandocfilters import toJSONFilter, Para, Str
390 | 
391 |         def func(key, value, format, meta):
392 |             if key == "Para":
393 |                 return Para(value + [Str("{{0}}-")])
394 | 
395 |         if __name__ == "__main__":
396 |             toJSONFilter(func)
397 |         
398 |         """
399 |         python = textwrap.dedent(python)
400 |         python = python.format(sys.executable)
401 | 
402 |         with closed_tempfile(".lua", lua.format(1)) as temp1, closed_tempfile(".py", python.format(2)) as temp2:
403 |             os.chmod(temp2, 0o755)
404 | 
405 |             with closed_tempfile(".lua", lua.format(3)) as temp3, closed_tempfile(".py", python.format(4)) as temp4:
406 |                 os.chmod(temp4, 0o755)
407 | 
408 |                 output = pypandoc.convert_text(
409 |                     markdown_source, to="html", format="md", outputfile=None, filters=[temp1, temp2, temp3, temp4]
410 |                 ).strip()
411 |                 expected = "<p>-0-1-2-3-4-</p>"
412 |                 try:
413 |                     self.assertEquals(output, expected)
414 |                 except AttributeError:
415 |                     # python 3.12 doesn't have assertEqual
416 |                     self.assertEqual(output, expected)
417 | 
418 |                 output = pypandoc.convert_text(
419 |                     markdown_source, to="html", format="md", outputfile=None, filters=[temp3, temp1, temp4, temp2]
420 |                 ).strip()
421 |                 expected = "<p>-0-3-1-4-2-</p>"
422 |                 try:
423 |                     self.assertEquals(output, expected)
424 |                 except AttributeError:
425 |                     # python 3.12 doesn't have assertEqual
426 |                     self.assertEqual(output, expected)
427 | 
428 |     def test_classify_pandoc_logging(self):
429 |         
430 |         test = ("[WARNING] This is some message on\ntwo lines\n"
431 |                 "[ERROR] This is a second message.")
432 |         
433 |         expected_levels = [30, 40]
434 |         expected_msgs = ["This is some message on\ntwo lines",
435 |                          "This is a second message."]
436 |         
437 |         for i, (l, m) in enumerate(pypandoc._classify_pandoc_logging(test)):
438 |             self.assertEqual(expected_levels[i], l)
439 |             self.assertEqual(expected_msgs[i], m)
440 | 
441 | 
442 |     def test_classify_pandoc_logging_default(self):
443 |         
444 |         test = ("This is some message on\ntwo lines\n"
445 |                 "[ERROR] This is a second message.")
446 |         expected_levels = [30, 40]
447 |         expected_msgs = ["This is some message on\ntwo lines",
448 |                          "This is a second message."]
449 |         
450 |         for i, (l, m) in enumerate(pypandoc._classify_pandoc_logging(test)):
451 |             self.assertEqual(expected_levels[i], l)
452 |             self.assertEqual(expected_msgs[i], m)
453 | 
454 | 
455 |     def test_classify_pandoc_logging_invalid_level(self):
456 |         
457 |         test = ("[WARN] This is some message on\ntwo lines\n"
458 |                 "[ERR] This is a second message.\n"
459 |                 "[ERROR] This is a third message.")
460 |         expected_levels = [30, 30, 40]
461 |         expected_msgs = ["This is some message on\ntwo lines",
462 |                          "This is a second message.",
463 |                          "This is a third message."]
464 |         
465 |         for i, (l, m) in enumerate(pypandoc._classify_pandoc_logging(test)):
466 |             self.assertEqual(expected_levels[i], l)
467 |             self.assertEqual(expected_msgs[i], m)
468 | 
469 | 
470 |     def test_conversion_stderr(self):
471 |         
472 |         # Clear logger handlers
473 |         logger = logging.getLogger("pypandoc")
474 |         logger.handlers = []
475 |         
476 |         with closed_tempfile('.docx') as file_name:
477 |             text = ('![Mock](missing.png)\n'
478 |                     '![Mock](missing.png)\n')
479 |             with capture(pypandoc.convert_text,
480 |                          text,
481 |                          to='docx',
482 |                          format='md',
483 |                          outputfile=file_name) as output:
484 |                 output = re.sub(r'\r', '', output)
485 |                 output = output.replace("'missing.png'",
486 |                                         "missing.png")
487 |                 output = output.lower()
488 |                 print(output)
489 |                 assert "[warning] could not fetch resource missing.png" in output
490 | 
491 |     def test_conversion_stderr_nullhandler(self):
492 |         
493 |         # Replace any logging handlers with a null handler
494 |         logger = logging.getLogger("pypandoc")
495 |         logger.handlers = [logging.NullHandler()]
496 |         
497 |         with closed_tempfile('.docx') as file_name:
498 |             text = ('![Mock](missing.png)\n'
499 |                     '![Mock](missing.png)\n')
500 |             with capture(pypandoc.convert_text,
501 |                          text,
502 |                          to='docx',
503 |                          format='md',
504 |                          outputfile=file_name) as output:
505 |                 self.assertFalse(output)
506 | 
507 | 
508 |     def test_conversion_error(self):
509 |         # pandoc dies on wrong commandline arguments
510 |         def f():
511 |             pypandoc.convert_text('<h1>Primary Heading</h1>', 'md', format='html', extra_args=["--blah"])
512 | 
513 |         with self.assertRaisesRegex(RuntimeError, 'Pandoc died with exitcode "6" during conversion: Unknown option --blah'):
514 |             f()
515 | 
516 |     def test_unicode_input(self):
517 |         # make sure that pandoc always returns unicode and does not mishandle it
518 |         expected = u'üäöîôû{0}'.format(os.linesep)
519 |         written = pypandoc.convert_text(u'<p>üäöîôû</p>', 'md', format='html')
520 |         self.assertTrue(isinstance(written, unicode_type))
521 |         self.assertEqualExceptForNewlineEnd(expected, written)
522 |         bytes = u'<p>üäöîôû</p>'.encode("utf-8")
523 |         written = pypandoc.convert_text(bytes, 'md', format='html')
524 |         self.assertTrue(expected == written)
525 |         self.assertTrue(isinstance(written, unicode_type))
526 | 
527 |         # Only use german umlauts in the next test, as iso-8859-15 covers that
528 |         expected = u'äüäö{0}'.format(os.linesep)
529 |         bytes = u'<p>äüäö</p>'.encode("iso-8859-15")
530 | 
531 |         # Without encoding, this fails as we expect utf-8 per default
532 | 
533 |         def f():
534 |             written = pypandoc.convert_text(bytes, 'md', format='html')
535 | 
536 |             assert expected != written
537 | 
538 |         def f():
539 |             # we have to use something which interprets '\xa4', so latin and -1 does not work :-/
540 |             written = pypandoc.convert_text(bytes, 'md', format='html', encoding="utf-16")
541 | 
542 |             assert expected != written
543 |         # with the right encoding it should work...
544 |         written = pypandoc.convert_text(bytes, 'md', format='html', encoding="iso-8859-15")
545 |         self.assertEqualExceptForNewlineEnd(expected, written)
546 |         self.assertTrue(isinstance(written, unicode_type))
547 | 
548 |     def test_conversion_from_non_plain_text_file(self):
549 |         with closed_tempfile('.docx') as file_name:
550 |             expected = u'some title{0}=========={0}{0}'.format(os.linesep)
551 |             # let's just test conversion (to and) from docx, testing e.g. odt
552 |             # as well would really be testing pandoc rather than pypandoc
553 |             received = pypandoc.convert_text('# some title\n', to='docx', format='md', outputfile=file_name)
554 |             self.assertEqualExceptForNewlineEnd("", received)
555 |             received = pypandoc.convert_file(file_name, to='rst')
556 |             self.assertEqualExceptForNewlineEnd(expected, received)
557 | 
558 |     def test_pdf_conversion(self):
559 |         with closed_tempfile('.pdf') as file_name:
560 |             ret = pypandoc.convert_text('# some title\n', to='pdf', format='md', outputfile=file_name)
561 |             assert ret == ""
562 |             with io.open(file_name, mode='rb') as f:
563 |                 written = f.read()
564 |             assert written[:4] == b"%PDF"
565 |             # TODO: find a test for the content?
566 | 
567 |         def f():
568 |             # needs an outputfile
569 |             pypandoc.convert_text('# some title\n', to='pdf', format='md')
570 | 
571 |         with self.assertRaisesRegex(RuntimeError, "Output to pdf only works by using a outputfile"):
572 |             f()
573 | 
574 |         # outputfile needs to end in pdf
575 |         with closed_tempfile('.WRONG') as file_name:
576 |             def str_filename():
577 |                 pypandoc.convert_text('# some title\n', to='pdf', format='md', outputfile=file_name)
578 | 
579 |             def path_filename():
580 |                 pypandoc.convert_text('# some title\n', to='pdf', format='md', outputfile=Path(file_name))
581 | 
582 |             with self.assertRaisesRegex(RuntimeError, 'PDF output needs an outputfile with ".pdf" as a fileending'):
583 |                 str_filename()
584 |                 path_filename()
585 | 
586 |         # no extensions allowed
587 |         with closed_tempfile('.pdf') as file_name:
588 |             def f():
589 |                 pypandoc.convert_text('# some title\n', to='pdf+something', format='md', outputfile=file_name)
590 | 
591 |             with self.assertRaisesRegex(RuntimeError, r"PDF output can't contain any extensions: pdf\+something"):
592 |                 f()
593 | 
594 |     def test_get_pandoc_path(self):
595 |         result = pypandoc.get_pandoc_path()
596 |         assert "pandoc" in result
597 | 
598 |     def test_call_with_nonexisting_file(self):
599 |         files = ['/file/does/not/exists.md',
600 |                  'file:///file/does/not/exists.md'
601 |                  '',
602 |                  42,
603 |                  None
604 |                  ]
605 | 
606 |         def f(filepath):
607 |             pypandoc.convert_file(filepath, 'rst')
608 | 
609 |         for filepath in files:
610 |             with self.assertRaisesRegex(RuntimeError, "source_file is not a valid path"):
611 |                 f(filepath)
612 | 
613 |     def test_convert_text_with_existing_file(self):
614 |         with closed_tempfile('.md', text='# some title\n') as file_name:
615 |             received = pypandoc.convert_text(file_name, 'rst', format='md')
616 |             self.assertTrue("title" not in received)
617 | 
618 |             # The following is a problematic case
619 |             received = pypandoc.convert_file(file_name, 'rst', format='md')
620 |             self.assertTrue("title" in received)
621 | 
622 |     def create_sample_lua(self):
623 |         args = [pypandoc.get_pandoc_path(), '--print-default-data-file', 'sample.lua']
624 |         p = subprocess.Popen(args, stdout=subprocess.PIPE)
625 |         out, err = p.communicate()
626 |         return out.decode('utf-8')
627 | 
628 |     def test_basic_conversion_from_file_pathlib(self):
629 |         with closed_tempfile('.md', text='# some title\n') as file_name:
630 |             expected = u'some title{0}=========={0}{0}'.format(os.linesep)
631 |             received_from_str_filename_input = pypandoc.convert_file(file_name, 'rst')
632 |             received_from_path_filename_input = pypandoc.convert_file(Path(file_name), 'rst')
633 |             self.assertEqualExceptForNewlineEnd(expected, received_from_str_filename_input)
634 |             self.assertEqualExceptForNewlineEnd(expected, received_from_path_filename_input)
635 | 
636 |     def test_basic_conversion_from_multiple_files_pathlib(self):
637 |         with closed_tempfile('.md', text='some title') as file_name1:
638 |             with closed_tempfile('.md', text='some title') as file_name2:
639 |                 expected = '<p>some title</p>\n<p>some title</p>'
640 |                 received_from_str_filename_input = pypandoc.convert_file([file_name1, file_name2], 'html')
641 |                 received_from_path_filename_input = pypandoc.convert_file([Path(file_name1), Path(file_name2)], 'html')
642 |                 self.assertEqualExceptForNewlineEnd(expected, received_from_str_filename_input)
643 |                 self.assertEqualExceptForNewlineEnd(expected, received_from_path_filename_input)
644 | 
645 |     def test_basic_conversion_from_file_pattern_pathlib_glob(self):
646 |         received_from_str_filename_input = pypandoc.convert_file("./*.md", 'html').lower()
647 |         received_from_path_filename_input = pypandoc.convert_file(Path(".").glob("*.md"), 'html').lower()
648 |         assert received_from_str_filename_input == received_from_path_filename_input
649 | 
650 |     def test_basic_conversion_from_file_pattern_with_input_list_pathlib_glob(self):
651 |         received_from_str_filename_input = pypandoc.convert_file(["./*.md", "./*.md"], 'html').lower()
652 |         received_from_path_filename_input = pypandoc.convert_file([*Path(".").glob("*.md"), *Path(".").glob("*.md")],
653 |                                                                   'html').lower()
654 |         assert received_from_str_filename_input == received_from_path_filename_input
655 | 
656 |     def test_basic_conversion_to_pathlib_file(self):
657 |         with closed_tempfile('.rst', ) as file_name:
658 |             expected = u'some title{0}=========={0}{0}'.format(os.linesep)
659 |             received = pypandoc.convert_text('# some title\n', to='rst', format='md', outputfile=Path(file_name))
660 |             self.assertEqualExceptForNewlineEnd("", received)
661 |             with io.open(file_name) as f:
662 |                 written = f.read()
663 |             self.assertEqualExceptForNewlineEnd(expected, written)
664 | 
665 |     def assertEqualExceptForNewlineEnd(self, expected, received):  # noqa
666 |         # output written to a file does not seem to have os.linesep
667 |         # handle everything here by replacing the os linesep by a simple \n
668 |         expected = expected.replace(os.linesep, "\n")
669 |         received = received.replace(os.linesep, "\n")
670 |         self.assertEqual(expected.rstrip('\n'), received.rstrip('\n'))
671 | 
672 | 
673 | if __name__ == '__main__':
674 |     suite = unittest.TestLoader().loadTestsFromTestCase(TestPypandoc)
675 |     ret = unittest.TextTestRunner(verbosity=2).run(suite)
676 |     sys.exit(0 if ret.wasSuccessful() else 1)
677 | 


--------------------------------------------------------------------------------