[](https://coveralls.io/github/collective/zpretty?branch=master)
[](https://results.pre-commit.ci/latest/github/collective/zpretty/master)
A tool to format in a **very opinionated** way HTML, XML and text
containing XML snippets.
It satisfies a primary need: decrease the pain of diffing HTML/XML.
For this reason `zpretty` formats the markup following these rules of
thumb:
- maximize the vertical space/decrease the line length
- attributes should be sorted consistently
- attribute sorting is first semantic and then alphabetic
This tool understands the [TAL
language](https://en.wikipedia.org/wiki/Template_Attribute_Language) and
has some features dedicated to it.
This tool is not a linter! If you are looking for linters safe bets are
[Tidy](https://www.html-tidy.org/) and
[xmllint](http://xmlsoft.org/xmllint.html).
You may have parsing problems! `zpretty` will close for you some known
self closing tags, like `input` and `img`, that are allowed to be open
in HTML.
`zpretty` is not clever enough to understand correctly valueless
attributes! Some work is ongoing, but it works best with \"normal\"
attributes.
Lack of feature/slowness are a known issue. For the moment the
development focused in having a working tool. So it works fast enough:
less than a second to format a \~100k file. New features are planned and
also huge perfomance boost can be easily obtained. Anyway `zpretty` is
not your option for formatting large files (\> 1 MB).
See [TODO section](#todo_section) to know what is forecast for the
future.
The source code and the issue tracker are hosted on
[GitHub](https://github.com/collective/zpretty).
# INSTALL
The suggested installation method is using
[pip](https://pypi.python.org/pypi/pip/):
```bash
python3 -m pip install --user zpretty
```
The latest release of `zpretty` requires Python3. If you need to use
Python2.7 use `zpretty` 0.9.x.
# USAGE
Basic usage:
```console
$ zpretty -h
usage: zpretty [-h] [--encoding ENCODING] [-i] [-v] [-x] [-z] [--check]
[--include INCLUDE] [--exclude EXCLUDE]
[--extend-exclude EXTEND_EXCLUDE]
[paths ...]
positional arguments:
paths The list of files or directory to prettify (defaults to
stdin). If a directory is passed, all files and
directories matching the regular expression passed to
--include will be prettified.
options:
-h, --help show this help message and exit
--encoding ENCODING The file encoding (defaults to utf8)
-i, --inplace Format files in place (overwrite existing file)
-v, --version Show zpretty version number
-x, --xml Treat the input file(s) as XML
-z, --zcml Treat the input file(s) as XML. Follow the ZCML
styleguide
--check Return code 0 if nothing would be changed, 1 if some
files would be reformatted
--include INCLUDE A regular expression that matches files and directories
that should be included on recursive searches. An empty
value means all files are included regardless of the
name. Use forward slashes for directories on all
platforms (Windows, too). Exclusions are calculated
first, inclusions later. [default:
\.(html|pt|xml|zcml)$]
--exclude EXCLUDE A regular expression that matches files and directories
that should be excluded on recursive searches. An empty
value means no paths are excluded. Use forward slashes
for directories on all platforms (Windows, too).
Exclusions are calculated first, inclusions later.
[default: /(\.direnv|\.eggs|\.git|\.hg|\.mypy_cache|\.no
x|\.tox|\.venv|venv|\.svn|\.ipynb_checkpoints|_build|buc
k-out|build|dist|__pypackages__)/]
--extend-exclude EXTEND_EXCLUDE
Like --exclude, but adds additional files and
directories on top of the excluded ones. (Useful if you
simply want to add to the default)
The default exclude pattern is: `/(\.direnv|\.eggs|\.git|\.hg|\.mypy_cache|\.nox
|\.tox|\.venv|venv|\.svn|\.ipynb_checkpoints|_build|buck-
out|build|dist|__pypackages__)/`
```
Without parameters constraining the file type (e.g. `-x`, `-z`, \...)
`zpretty` will try to guess the right options for you.
Example:
```console
zpretty hello_world.html
```
# pre-commit support
`zpretty` can be used as a [pre-commit](https://pre-commit.com/) hook.
To do so, add the following to your `.pre-commit-config.yaml`:
```yaml
- repo: https://github.com/collective/zpretty
rev: FIXME
hooks:
- id: zpretty
```
# VSCode extension
There is a VSCode extension that uses `zpretty`:
- [https://marketplace.visualstudio.com/items?itemName=erral.erral-zcmlLanguageConfiguration](https://marketplace.visualstudio.com/items?itemName=erral.erral-zcmlLanguageConfiguration)
Thanks to @erral for the work!
# DEVELOP
```bash
git clone ...
cd zpretty
make
```
# RUNNING TESTS
```bash
make test
```
# Changelog
## 3.1.0 (2023-06-30)
- No changes were made from the latest alpha version
[ale-rt]
## 3.1.0a2 (2023-05-09)
- Improve the regular expression that matches the entities
(Fixes #130)
[ale-rt]
## 3.1.0a1 (2023-05-04)
- Add command line parameters to include/exclude files and folders
(Implements #96)
[ale-rt]
- Be tolerant with characters forbidden in XML when dealing with tal attributes
(See #125)
[ale-rt]
## 3.0.4 (2023-04-20)
- Fix bogus ampersands in attributes
(Fixes #116)
[ale-rt]
## 3.0.3 (2023-03-26)
- Handle HTML files with an XML preamble before the doctype.
(Fixes #118)
[ale-rt]
## 3.0.2 (2023-02-26)
- Handle forbidden characters in attributes properly
(Fixes #110)
[ale-rt]
- Fix attribute with a value containing double quotes
(Fixes #109)
[ale-rt]
## 3.0.1 (2023-02-09)
- Fix an issue with empty lines inside an attribute.
(Fixes #106)
[ale-rt]
## 3.0.0 (2023-02-09)
- The pre-commit hook now modifies fixes the files instead of just checking
if they should be fixed
[ale-rt]
- Fix the check behavior when multiple files are passed
[ale-rt]
- Improve the check that sniffs html files
(Fixes #89)
[ale-rt]
## 2.4.1 (2022-10-25)
- XML files with newlines between attributes are properly formatted
(Fixes #84)
[ale-rt]
- Do not tamper attributes in XML as if they were a page template attribute
(Fixes #85)
[ale-rt]
## 2.4.0 (2022-10-22)
- Prevent fiddling around with custom entity declaration (Fixes #80)
[ale-rt]
- Add support for Python 3.11.
[ale-rt]
- Drop support for Python 3.6.
[ale-rt]
## 2.3.1 (2022-09-30)
- Do not try to do anything on CDATAs (Fixes #76)
[ale-rt]
## 2.3.0 (2022-09-26)
- Added a -v/--version option [ale-rt]
## 2.3.0a4 (2022-09-24)
- Remove custom tree builder which is not used anymore [ale-rt]
- Fix entity sustitution in XML (Fixes #48, Refs #71) [ale-rt]
## 2.3.0a3 (2022-07-08)
- Do not escape entities inside the script and style tags (Fixes #57) [ale-rt]
## 2.3.0a2 (2022-07-08)
- Fix release
## 2.3.0a1 (2022-07-08)
- Preserve whitespace in XML documents and `pre` elements (Fixes #64) [ale-rt]
- Improve doctype handling [ale-rt]
- Do not kill XML documents with a doctype (Fixes #47) [ale-rt]
- Support Python 3.10 [ale-rt]
## 2.2.0 (2021-12-06)
- Add a `--check` command line parameter (Fixes #49) [ale-rt]
- Now the package is `pre-commit` compatibile (Fixes #50) [ale-rt]
## 2.1.0 (2021-02-12)
- Remove unused `autofix` method [ale-rt]
- Do not render a spurious `=""` when new lines appear inside a tag (Refs. #35) [ale-rt]
- The attributes renderer knows about the element indentation
and for indents the attributes consequently [ale-rt]
- The ZCML element has now its custom tag templates, this simplifies the code [ale-rt]
- Attributes content spanning multiple lines is not indented anymore (Refs. #17) [ale-rt]
- Improved sorting for zcml attributes (Refs. #11) [ale-rt]
- Code is compliant with black 20.8b1 [ale-rt]
- Switch to pytest for running tests [ale-rt]
- Upgrade dev requirements [ale-rt]
- Support Python 3.9 [ale-rt]
## 2.0.0 (2020-05-28)
- Updated the list of self closing elements and boolean attributes [ale-rt]
## 1.0.3 (2020-05-22)
- Fix unwanted newlines (#20)
## 1.0.2 (2019-11-03)
- In Python3.8 quotes in attributes were escaped
- Fix output again on file and stdout [ale-rt]
## 1.0.1 (2019-10-28)
- Fix output on file [ale-rt]
## 1.0.0 (2019-10-27)
- Support Python3 only [ale-rt]
## 0.9.3 (2017-05-06)
- Last release that supports Python2.7
- Fix text method
- Preserve entities in text
- Added an `--encoding` parameter
- Added an `--xml` parameter to force xml parsing
- Choose the better parser according to the given filename if no parser is forced
- Process stdin if `-` is in the arguments or no arguments are passed [ale-rt]
## 0.9.2 (2017-02-27)
- Small modification for the order of the zcml attributes
- Auto add a new line to the end of the prettified files
- Self heal open self closing tag. [ale-rt]
## 0.9.1.1 (2017-02-18)
- Fixed bad release. [ale-rt]
## 0.9.1 (2017-02-18)
- Initial support for zcml style guide (\#3). [ale-rt]
## 0.9.0 (2017-02-11)
- Initial release. [ale-rt]
Raw data
{
"_id": null,
"home_page": "https://github.com/collective/zpretty",
"name": "zpretty",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "Formatter,HTML,Prettifier,Pretty print,TAL,XML,ZPT",
"author": "Alessandro Pisa",
"author_email": "alessandro.pisa@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/23/c4/41b713c4ce58fd86dc8c1cdcf47c262451fa886173d477c63844f6111945/zpretty-3.1.0.tar.gz",
"platform": null,
"description": "\n\n[](https://coveralls.io/github/collective/zpretty?branch=master)\n\n[](https://results.pre-commit.ci/latest/github/collective/zpretty/master)\n\nA tool to format in a **very opinionated** way HTML, XML and text\ncontaining XML snippets.\n\nIt satisfies a primary need: decrease the pain of diffing HTML/XML.\n\nFor this reason `zpretty` formats the markup following these rules of\nthumb:\n\n- maximize the vertical space/decrease the line length\n- attributes should be sorted consistently\n- attribute sorting is first semantic and then alphabetic\n\nThis tool understands the [TAL\nlanguage](https://en.wikipedia.org/wiki/Template_Attribute_Language) and\nhas some features dedicated to it.\n\nThis tool is not a linter! If you are looking for linters safe bets are\n[Tidy](https://www.html-tidy.org/) and\n[xmllint](http://xmlsoft.org/xmllint.html).\n\nYou may have parsing problems! `zpretty` will close for you some known\nself closing tags, like `input` and `img`, that are allowed to be open\nin HTML.\n\n`zpretty` is not clever enough to understand correctly valueless\nattributes! Some work is ongoing, but it works best with \\\"normal\\\"\nattributes.\n\nLack of feature/slowness are a known issue. For the moment the\ndevelopment focused in having a working tool. So it works fast enough:\nless than a second to format a \\~100k file. New features are planned and\nalso huge perfomance boost can be easily obtained. Anyway `zpretty` is\nnot your option for formatting large files (\\> 1 MB).\n\nSee [TODO section](#todo_section) to know what is forecast for the\nfuture.\n\nThe source code and the issue tracker are hosted on\n[GitHub](https://github.com/collective/zpretty).\n\n# INSTALL\n\nThe suggested installation method is using\n[pip](https://pypi.python.org/pypi/pip/):\n\n```bash\npython3 -m pip install --user zpretty\n```\n\nThe latest release of `zpretty` requires Python3. If you need to use\nPython2.7 use `zpretty` 0.9.x.\n\n# USAGE\n\nBasic usage:\n\n```console\n$ zpretty -h\nusage: zpretty [-h] [--encoding ENCODING] [-i] [-v] [-x] [-z] [--check]\n [--include INCLUDE] [--exclude EXCLUDE]\n [--extend-exclude EXTEND_EXCLUDE]\n [paths ...]\n\npositional arguments:\n paths The list of files or directory to prettify (defaults to\n stdin). If a directory is passed, all files and\n directories matching the regular expression passed to\n --include will be prettified.\n\noptions:\n -h, --help show this help message and exit\n --encoding ENCODING The file encoding (defaults to utf8)\n -i, --inplace Format files in place (overwrite existing file)\n -v, --version Show zpretty version number\n -x, --xml Treat the input file(s) as XML\n -z, --zcml Treat the input file(s) as XML. Follow the ZCML\n styleguide\n --check Return code 0 if nothing would be changed, 1 if some\n files would be reformatted\n --include INCLUDE A regular expression that matches files and directories\n that should be included on recursive searches. An empty\n value means all files are included regardless of the\n name. Use forward slashes for directories on all\n platforms (Windows, too). Exclusions are calculated\n first, inclusions later. [default:\n \\.(html|pt|xml|zcml)$]\n --exclude EXCLUDE A regular expression that matches files and directories\n that should be excluded on recursive searches. An empty\n value means no paths are excluded. Use forward slashes\n for directories on all platforms (Windows, too).\n Exclusions are calculated first, inclusions later.\n [default: /(\\.direnv|\\.eggs|\\.git|\\.hg|\\.mypy_cache|\\.no\n x|\\.tox|\\.venv|venv|\\.svn|\\.ipynb_checkpoints|_build|buc\n k-out|build|dist|__pypackages__)/]\n --extend-exclude EXTEND_EXCLUDE\n Like --exclude, but adds additional files and\n directories on top of the excluded ones. (Useful if you\n simply want to add to the default)\n\nThe default exclude pattern is: `/(\\.direnv|\\.eggs|\\.git|\\.hg|\\.mypy_cache|\\.nox\n|\\.tox|\\.venv|venv|\\.svn|\\.ipynb_checkpoints|_build|buck-\nout|build|dist|__pypackages__)/`\n```\n\nWithout parameters constraining the file type (e.g. `-x`, `-z`, \\...)\n`zpretty` will try to guess the right options for you.\n\nExample:\n\n```console\nzpretty hello_world.html\n```\n\n# pre-commit support\n\n`zpretty` can be used as a [pre-commit](https://pre-commit.com/) hook.\nTo do so, add the following to your `.pre-commit-config.yaml`:\n\n```yaml\n- repo: https://github.com/collective/zpretty\n rev: FIXME\n hooks:\n - id: zpretty\n```\n\n# VSCode extension\n\nThere is a VSCode extension that uses `zpretty`:\n\n- [https://marketplace.visualstudio.com/items?itemName=erral.erral-zcmlLanguageConfiguration](https://marketplace.visualstudio.com/items?itemName=erral.erral-zcmlLanguageConfiguration)\n\nThanks to @erral for the work!\n\n# DEVELOP\n\n```bash\ngit clone ...\ncd zpretty\nmake\n```\n\n# RUNNING TESTS\n\n```bash\nmake test\n```\n\n# Changelog\n\n## 3.1.0 (2023-06-30)\n\n\n- No changes were made from the latest alpha version\n [ale-rt]\n\n## 3.1.0a2 (2023-05-09)\n\n- Improve the regular expression that matches the entities\n (Fixes #130)\n [ale-rt]\n\n## 3.1.0a1 (2023-05-04)\n\n- Add command line parameters to include/exclude files and folders\n (Implements #96)\n [ale-rt]\n- Be tolerant with characters forbidden in XML when dealing with tal attributes\n (See #125)\n [ale-rt]\n\n## 3.0.4 (2023-04-20)\n\n- Fix bogus ampersands in attributes\n (Fixes #116)\n [ale-rt]\n\n## 3.0.3 (2023-03-26)\n\n- Handle HTML files with an XML preamble before the doctype.\n (Fixes #118)\n [ale-rt]\n\n## 3.0.2 (2023-02-26)\n\n- Handle forbidden characters in attributes properly\n (Fixes #110)\n [ale-rt]\n- Fix attribute with a value containing double quotes\n (Fixes #109)\n [ale-rt]\n\n## 3.0.1 (2023-02-09)\n\n- Fix an issue with empty lines inside an attribute.\n (Fixes #106)\n [ale-rt]\n\n## 3.0.0 (2023-02-09)\n\n- The pre-commit hook now modifies fixes the files instead of just checking\n if they should be fixed\n [ale-rt]\n- Fix the check behavior when multiple files are passed\n [ale-rt]\n- Improve the check that sniffs html files\n (Fixes #89)\n [ale-rt]\n\n## 2.4.1 (2022-10-25)\n\n- XML files with newlines between attributes are properly formatted\n (Fixes #84)\n [ale-rt]\n- Do not tamper attributes in XML as if they were a page template attribute\n (Fixes #85)\n [ale-rt]\n\n## 2.4.0 (2022-10-22)\n\n- Prevent fiddling around with custom entity declaration (Fixes #80)\n [ale-rt]\n- Add support for Python 3.11.\n [ale-rt]\n- Drop support for Python 3.6.\n [ale-rt]\n\n## 2.3.1 (2022-09-30)\n\n- Do not try to do anything on CDATAs (Fixes #76)\n [ale-rt]\n\n## 2.3.0 (2022-09-26)\n\n- Added a -v/--version option [ale-rt]\n\n## 2.3.0a4 (2022-09-24)\n\n- Remove custom tree builder which is not used anymore [ale-rt]\n- Fix entity sustitution in XML (Fixes #48, Refs #71) [ale-rt]\n\n## 2.3.0a3 (2022-07-08)\n\n- Do not escape entities inside the script and style tags (Fixes #57) [ale-rt]\n\n## 2.3.0a2 (2022-07-08)\n\n- Fix release\n\n## 2.3.0a1 (2022-07-08)\n\n- Preserve whitespace in XML documents and `pre` elements (Fixes #64) [ale-rt]\n- Improve doctype handling [ale-rt]\n- Do not kill XML documents with a doctype (Fixes #47) [ale-rt]\n- Support Python 3.10 [ale-rt]\n\n## 2.2.0 (2021-12-06)\n\n- Add a `--check` command line parameter (Fixes #49) [ale-rt]\n- Now the package is `pre-commit` compatibile (Fixes #50) [ale-rt]\n\n## 2.1.0 (2021-02-12)\n\n- Remove unused `autofix` method [ale-rt]\n- Do not render a spurious `=\"\"` when new lines appear inside a tag (Refs. #35) [ale-rt]\n- The attributes renderer knows about the element indentation\n and for indents the attributes consequently [ale-rt]\n- The ZCML element has now its custom tag templates, this simplifies the code [ale-rt]\n- Attributes content spanning multiple lines is not indented anymore (Refs. #17) [ale-rt]\n- Improved sorting for zcml attributes (Refs. #11) [ale-rt]\n- Code is compliant with black 20.8b1 [ale-rt]\n- Switch to pytest for running tests [ale-rt]\n- Upgrade dev requirements [ale-rt]\n- Support Python 3.9 [ale-rt]\n\n## 2.0.0 (2020-05-28)\n\n- Updated the list of self closing elements and boolean attributes [ale-rt]\n\n## 1.0.3 (2020-05-22)\n\n- Fix unwanted newlines (#20)\n\n## 1.0.2 (2019-11-03)\n\n- In Python3.8 quotes in attributes were escaped\n- Fix output again on file and stdout [ale-rt]\n\n## 1.0.1 (2019-10-28)\n\n- Fix output on file [ale-rt]\n\n## 1.0.0 (2019-10-27)\n\n- Support Python3 only [ale-rt]\n\n## 0.9.3 (2017-05-06)\n\n- Last release that supports Python2.7\n- Fix text method\n- Preserve entities in text\n- Added an `--encoding` parameter\n- Added an `--xml` parameter to force xml parsing\n- Choose the better parser according to the given filename if no parser is forced\n- Process stdin if `-` is in the arguments or no arguments are passed [ale-rt]\n\n## 0.9.2 (2017-02-27)\n\n- Small modification for the order of the zcml attributes\n- Auto add a new line to the end of the prettified files\n- Self heal open self closing tag. [ale-rt]\n\n## 0.9.1.1 (2017-02-18)\n\n- Fixed bad release. [ale-rt]\n\n## 0.9.1 (2017-02-18)\n\n- Initial support for zcml style guide (\\#3). [ale-rt]\n\n## 0.9.0 (2017-02-11)\n\n- Initial release. [ale-rt]\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "An opinionated HTML/XML soup formatter",
"version": "3.1.0",
"project_urls": {
"Homepage": "https://github.com/collective/zpretty"
},
"split_keywords": [
"formatter",
"html",
"prettifier",
"pretty print",
"tal",
"xml",
"zpt"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "23c441b713c4ce58fd86dc8c1cdcf47c262451fa886173d477c63844f6111945",
"md5": "a4e9afeba74195cafc4dc70981979ddd",
"sha256": "6ce274007e61eb449a4d07f58d2ec31b07b1aea0bbe1d37e423dc245a16b2293"
},
"downloads": -1,
"filename": "zpretty-3.1.0.tar.gz",
"has_sig": false,
"md5_digest": "a4e9afeba74195cafc4dc70981979ddd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 36441,
"upload_time": "2023-06-30T12:51:40",
"upload_time_iso_8601": "2023-06-30T12:51:40.541824Z",
"url": "https://files.pythonhosted.org/packages/23/c4/41b713c4ce58fd86dc8c1cdcf47c262451fa886173d477c63844f6111945/zpretty-3.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-30 12:51:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "collective",
"github_project": "zpretty",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "zpretty"
}
JSON
