# `latexminted` — Python library for LaTeX minted package
This Python package provides the Python side of the LaTeX
[`minted`](https://github.com/gpoore/minted) package. It performs syntax
highlighting using the [Pygments](https://pygments.org/) library. It also
provides several code formatting and manipulation features implemented in
Python that would be difficult to perform in LaTeX, such as dedenting code and
extracting code snippets from source files using regular expressions.
This package should only be installed manually if you need to use plugin
packages for Pygments. The package is bundled within TeX distributions as a
Python wheel along with the LaTeX `minted` package. Installing the LaTeX
`minted` package with your TeX distribution's package manager will also
install the `latexminted` Python package and all required Python libraries
within the TeX installation. If you do need Pygments plugins, then install
`latexminted` manually along with Pygments in a Python installation. Make
sure that the `latexminted` executable that is created as part of this process
has precedence on `PATH` over the `latexminted` executable in your TeX
installation. For Windows, precedence on either the system `PATH` or the user
`PATH` is usually sufficient, as long as the TeX installation is in a typical
location and any user Python executable is within a Python installation under
the user's home directory.
This Python package is specifically designed to be compatible with the LaTeX
security requirements for restricted shell escape executables. These trusted
executables can run during LaTeX compilation without requiring `-shell-escape`
or similar command-line options that allow arbitrary shell commands to be
executed.
## Configuration
Several `minted` settings with security implications can be customized with a
config file `.latexminted_config`. This config file is loaded by the
`latexminted` Python executable when it runs.
The `latexminted` Python executable looks for `.latexminted_config` files in
the following locations:
* User home directory, as found by Python's
[pathlib.Path.home()](https://docs.python.org/3/library/pathlib.html#pathlib.Path.home).
* `TEXMFHOME`. With MiKTeX on systems with multiple MiKTeX installations,
this will be the `TEXMFHOME` from the first MiKTeX installation on `PATH`.
With TeX Live on Windows systems with multiple TeX Live installations,
this will be the `TEXMFHOME` from the first TeX Live installation on
`PATH`. In all other cases, `TEXMFHOME` will correspond to the currently
active TeX installation. See the
[`latexrestricted`](https://github.com/gpoore/latexrestricted)
documentation for details. `latexrestricted` is used by the `latexminted`
Python executable to retrieve the value of `TEXMFHOME`.
* The current TeX working directory. Note that `enable_cwd_config` must be
set `true` in the `.latexminted_config` in the user home directory or in
the `TEXMFHOME` directory to enable this; `.latexminted_config` in the
current TeX working directory is not enabled by default for security
reasons. Even when a config file in the current TeX working directory is
enabled, it cannot be used to modify certain security-related settings.
Overall configuration is derived by merging all config files, with later files
in the list above having precedence over earlier files. Boolean and string
values are overwritten by later config files. Collection values (currently
only sets derived from lists) are merged with earlier values.
### File format
The `.latexminted_config` file may be in Python literal format (dicts and
lists of strings and bools), JSON, or TOML (requires Python 3.11+). It must
be encoded as UTF-8.
### Settings
* `security: dict[str, str | bool]`: These settings relate to `latexminted`
security. They can only be set in `.latexminted_config` in the user home
directory or in `TEXMFHOME`. They cannot be set in `.latexminted_config` in
the current TeX working directory.
- `enable_cwd_config: bool = False`: Load a `.latexminted_config` file from
the current TeX working directory if it exists. This is disabled by
default because the config file can enable `custom_lexers`, which is
equivalent to arbitrary code execution.
- `file_path_analysis: "resolve" | "string" = "resolve"`: This specifies
how `latexminted` determines whether files are readable and writable.
Relative file paths are always treated as being relative to the current
TeX working directory.
With `resolve`, any symlinks in file paths are resolved with the file
system before paths are compared with permitted LaTeX read/write
locations. Arbitrary relative paths including `..` are allowed so long as
the final location is permitted.
With `string`, paths are analyzed as strings in comparing them with
permitted LaTeX read/write locations. This follows the approach taken in
TeX's file system security. Paths cannot contain `..` to access a parent
directory, even if the parent directory is a valid location. Because
symlinks are not resolved with the file system, it is possible to access
locations outside permitted LaTeX read/write locations, if the permitted
locations contain symlinks to elsewhere.
- `permitted_pathext_file_extensions: list[str]`: As a security measure
under Windows, LaTeX cannot write files with file extensions in `PATHEXT`,
such as `.bat` and `.exe`. This setting allows `latexminted` to write
files with the specified file extensions, overriding LaTeX security. File
extensions should be in the form `.<ext>`, for example, `.bat`. This
setting is used in extracting source code from LaTeX documents and saving
it in standalone source files.
When these file extensions are enabled for writing, as a security measure
`latexminted` will only allow them to be created in *subdirectories* of
the current TeX working directory, `TEXMFOUTPUT`, and
`TEXMF_OUTPUT_DIRECTORY`. These files cannot be created directly under
the TeX working directory, `TEXMFOUTPUT`, and `TEXMF_OUTPUT_DIRECTORY`
because those locations are more likely to be used as a working directory
in a shell, and thus writing executable files in those locations would
increase the risk of accidental code execution.
* `custom_lexers: dict[str, str | list[str]]`: This is a mapping of custom
lexer file names to SHA256 hashes. Only custom lexers with these file names
and the corresponding hashes are permitted. Lists of hashes are allowed to
permit multiple versions of a lexer with a given file name. All other
custom lexers are prohibited, because loading custom lexers is equivalent to
arbitrary code execution. For example:
```
"custom_lexers": {
"mylexer.py": "<sha256>"
}
```
Note that this only applies to custom lexers in standalone Python files.
Lexers that are installed within Python as plugin packages work
automatically with Pygments and do not need to be enabled separately.
However, in that case it is necessary to install `latexminted` and Pygments
within a Python installation. When TeX package managers install
`latexminted` and Pygments within a TeX installation, these are not
compatible with Pygments plugin packages.
Raw data
{
"_id": null,
"home_page": null,
"name": "latexminted",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "LaTeX, syntax highlighting, Pygments",
"author": null,
"author_email": "\"Geoffrey M. Poore\" <gpoore@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f6/25/9547c7e7e9247f6013fe7924b42945f6a2413d2ab6949ccecd03626294ab/latexminted-0.2.0.tar.gz",
"platform": null,
"description": "# `latexminted` \u2014 Python library for LaTeX minted package\r\n\r\nThis Python package provides the Python side of the LaTeX\r\n[`minted`](https://github.com/gpoore/minted) package. It performs syntax\r\nhighlighting using the [Pygments](https://pygments.org/) library. It also\r\nprovides several code formatting and manipulation features implemented in\r\nPython that would be difficult to perform in LaTeX, such as dedenting code and\r\nextracting code snippets from source files using regular expressions.\r\n\r\nThis package should only be installed manually if you need to use plugin\r\npackages for Pygments. The package is bundled within TeX distributions as a\r\nPython wheel along with the LaTeX `minted` package. Installing the LaTeX\r\n`minted` package with your TeX distribution's package manager will also\r\ninstall the `latexminted` Python package and all required Python libraries\r\nwithin the TeX installation. If you do need Pygments plugins, then install\r\n`latexminted` manually along with Pygments in a Python installation. Make\r\nsure that the `latexminted` executable that is created as part of this process\r\nhas precedence on `PATH` over the `latexminted` executable in your TeX\r\ninstallation. For Windows, precedence on either the system `PATH` or the user\r\n`PATH` is usually sufficient, as long as the TeX installation is in a typical\r\nlocation and any user Python executable is within a Python installation under\r\nthe user's home directory.\r\n\r\nThis Python package is specifically designed to be compatible with the LaTeX\r\nsecurity requirements for restricted shell escape executables. These trusted\r\nexecutables can run during LaTeX compilation without requiring `-shell-escape`\r\nor similar command-line options that allow arbitrary shell commands to be\r\nexecuted.\r\n\r\n\r\n## Configuration\r\n\r\nSeveral `minted` settings with security implications can be customized with a\r\nconfig file `.latexminted_config`. This config file is loaded by the\r\n`latexminted` Python executable when it runs.\r\n\r\nThe `latexminted` Python executable looks for `.latexminted_config` files in\r\nthe following locations:\r\n\r\n * User home directory, as found by Python's\r\n [pathlib.Path.home()](https://docs.python.org/3/library/pathlib.html#pathlib.Path.home).\r\n\r\n * `TEXMFHOME`. With MiKTeX on systems with multiple MiKTeX installations,\r\n this will be the `TEXMFHOME` from the first MiKTeX installation on `PATH`.\r\n With TeX Live on Windows systems with multiple TeX Live installations,\r\n this will be the `TEXMFHOME` from the first TeX Live installation on\r\n `PATH`. In all other cases, `TEXMFHOME` will correspond to the currently\r\n active TeX installation. See the\r\n [`latexrestricted`](https://github.com/gpoore/latexrestricted)\r\n documentation for details. `latexrestricted` is used by the `latexminted`\r\n Python executable to retrieve the value of `TEXMFHOME`.\r\n\r\n * The current TeX working directory. Note that `enable_cwd_config` must be\r\n set `true` in the `.latexminted_config` in the user home directory or in\r\n the `TEXMFHOME` directory to enable this; `.latexminted_config` in the\r\n current TeX working directory is not enabled by default for security\r\n reasons. Even when a config file in the current TeX working directory is\r\n enabled, it cannot be used to modify certain security-related settings.\r\n\r\nOverall configuration is derived by merging all config files, with later files\r\nin the list above having precedence over earlier files. Boolean and string\r\nvalues are overwritten by later config files. Collection values (currently\r\nonly sets derived from lists) are merged with earlier values.\r\n\r\n### File format\r\n\r\nThe `.latexminted_config` file may be in Python literal format (dicts and\r\nlists of strings and bools), JSON, or TOML (requires Python 3.11+). It must\r\nbe encoded as UTF-8.\r\n\r\n### Settings\r\n\r\n* `security: dict[str, str | bool]`: These settings relate to `latexminted`\r\n security. They can only be set in `.latexminted_config` in the user home\r\n directory or in `TEXMFHOME`. They cannot be set in `.latexminted_config` in\r\n the current TeX working directory.\r\n\r\n - `enable_cwd_config: bool = False`: Load a `.latexminted_config` file from\r\n the current TeX working directory if it exists. This is disabled by\r\n default because the config file can enable `custom_lexers`, which is\r\n equivalent to arbitrary code execution.\r\n\r\n - `file_path_analysis: \"resolve\" | \"string\" = \"resolve\"`: This specifies\r\n how `latexminted` determines whether files are readable and writable.\r\n Relative file paths are always treated as being relative to the current\r\n TeX working directory.\r\n\r\n With `resolve`, any symlinks in file paths are resolved with the file\r\n system before paths are compared with permitted LaTeX read/write\r\n locations. Arbitrary relative paths including `..` are allowed so long as\r\n the final location is permitted.\r\n\r\n With `string`, paths are analyzed as strings in comparing them with\r\n permitted LaTeX read/write locations. This follows the approach taken in\r\n TeX's file system security. Paths cannot contain `..` to access a parent\r\n directory, even if the parent directory is a valid location. Because\r\n symlinks are not resolved with the file system, it is possible to access\r\n locations outside permitted LaTeX read/write locations, if the permitted\r\n locations contain symlinks to elsewhere.\r\n\r\n - `permitted_pathext_file_extensions: list[str]`: As a security measure\r\n under Windows, LaTeX cannot write files with file extensions in `PATHEXT`,\r\n such as `.bat` and `.exe`. This setting allows `latexminted` to write\r\n files with the specified file extensions, overriding LaTeX security. File\r\n extensions should be in the form `.<ext>`, for example, `.bat`. This\r\n setting is used in extracting source code from LaTeX documents and saving\r\n it in standalone source files.\r\n\r\n When these file extensions are enabled for writing, as a security measure\r\n `latexminted` will only allow them to be created in *subdirectories* of\r\n the current TeX working directory, `TEXMFOUTPUT`, and\r\n `TEXMF_OUTPUT_DIRECTORY`. These files cannot be created directly under\r\n the TeX working directory, `TEXMFOUTPUT`, and `TEXMF_OUTPUT_DIRECTORY`\r\n because those locations are more likely to be used as a working directory\r\n in a shell, and thus writing executable files in those locations would\r\n increase the risk of accidental code execution.\r\n\r\n* `custom_lexers: dict[str, str | list[str]]`: This is a mapping of custom\r\n lexer file names to SHA256 hashes. Only custom lexers with these file names\r\n and the corresponding hashes are permitted. Lists of hashes are allowed to\r\n permit multiple versions of a lexer with a given file name. All other\r\n custom lexers are prohibited, because loading custom lexers is equivalent to\r\n arbitrary code execution. For example:\r\n\r\n ```\r\n \"custom_lexers\": {\r\n \"mylexer.py\": \"<sha256>\"\r\n }\r\n ```\r\n\r\n Note that this only applies to custom lexers in standalone Python files.\r\n Lexers that are installed within Python as plugin packages work\r\n automatically with Pygments and do not need to be enabled separately.\r\n However, in that case it is necessary to install `latexminted` and Pygments\r\n within a Python installation. When TeX package managers install\r\n `latexminted` and Pygments within a TeX installation, these are not\r\n compatible with Pygments plugin packages.\r\n",
"bugtrack_url": null,
"license": "latexminted Python package Copyright (c) 2024 Geoffrey M. Poore This work may be distributed and/or modified under the conditions of the LaTeX Project Public License, either version 1.3c of this license or (at your option) any later version. The latest version of this license is in https://www.latex-project.org/lppl.txt and version 1.3c or later is part of all distributions of LaTeX version 2008 or later. This work has the LPPL maintenance status `maintained'. The Current Maintainer of this work is Geoffrey M. Poore. This work consists of the files in the latexminted Python package. ",
"summary": "Python library for LaTeX minted package",
"version": "0.2.0",
"project_urls": {
"changelog": "https://github.com/gpoore/minted/blob/main/python/CHANGELOG_LATEXMINTED_PYTHON_PACKAGE.md",
"homepage": "https://github.com/gpoore/minted/tree/main/python/",
"repository": "https://github.com/gpoore/minted"
},
"split_keywords": [
"latex",
" syntax highlighting",
" pygments"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "02b92e8a31e59abc0276361227521fadbef109024c4e9307f8bb6c0b2e29dd6b",
"md5": "71014cacd92a14c3134685da5ae50bfa",
"sha256": "0906874b0356c983abc54fd627b12379b9c133d92f9b9f4f8d200106d6a47e89"
},
"downloads": -1,
"filename": "latexminted-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "71014cacd92a14c3134685da5ae50bfa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 32796,
"upload_time": "2024-10-03T14:33:48",
"upload_time_iso_8601": "2024-10-03T14:33:48.712325Z",
"url": "https://files.pythonhosted.org/packages/02/b9/2e8a31e59abc0276361227521fadbef109024c4e9307f8bb6c0b2e29dd6b/latexminted-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f6259547c7e7e9247f6013fe7924b42945f6a2413d2ab6949ccecd03626294ab",
"md5": "e25df24c19360d39608c79ead498c159",
"sha256": "bc9ce236055872725f9809e893639e61910ec06b467e1672ba9dc3dfe06e66c5"
},
"downloads": -1,
"filename": "latexminted-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "e25df24c19360d39608c79ead498c159",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 26611,
"upload_time": "2024-10-03T14:33:50",
"upload_time_iso_8601": "2024-10-03T14:33:50.790354Z",
"url": "https://files.pythonhosted.org/packages/f6/25/9547c7e7e9247f6013fe7924b42945f6a2413d2ab6949ccecd03626294ab/latexminted-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-03 14:33:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gpoore",
"github_project": "minted",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "latexminted"
}
JSON
