Metadata-Version: 2.1
Name: zpretty
Version: 3.0.3
Summary: An opinionated HTML/XML soup formatter
Home-page: https://github.com/collective/zpretty
Author: Alessandro Pisa
Author-email: alessandro.pisa@gmail.com
License: BSD
Keywords: Formatter,HTML,Prettifier,Pretty print,TAL,XML,ZPT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Provides-Extra: test
Provides-Extra: development
License-File: LICENSE

![tests](https://github.com/collective/zpretty/workflows/tests/badge.svg)

[![image](https://coveralls.io/repos/github/collective/zpretty/badge.svg?branch=master)](https://coveralls.io/github/collective/zpretty?branch=master)

[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/collective/zpretty/master.svg)](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]
               [paths ...]

positional arguments:
    paths                The list of paths to prettify (defaults to stdin)

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
```

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
```

# TODO

- [ ] Valueless attributes are not allowed in XML
- [ ] Attributes are aligned in a strange way if previous sibling has no spaces
- [ ] TBD: Style attributes should be multiline

# Changelog

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]
