cleer

The rules are cleer... or at least that was the idea.

cleer is a customizable and extensible file formatter. Primarily made for Python (in Python), but works with any language.

It has a set of defaults that I have chosen for a specifically readable style. It does not try to make the smallest git diffs, but the most readable code. Objectively speaking of course (I like the formatting).

Installation

pip install cleer

CLI

The CLI is the primary interface. Use --help on the base or any command for all options.

cleer --help

Two main commands:

• inspect — JSON output of formatting violations
• format — format files in place

Both work on a single file or all matching files in a directory.

cleer inspect path/to/file.py
cleer inspect path/to/dir/
cleer format path/to/file.py
cleer format path/to/dir/

Inspect output

[
    {
        "path": "/full/path/to/file.py",
        "violations": [
            {
                "start_index": 49,
                "length": 22,
                "message": "Lines should not have any trailing whitespace."
            }
        ]
    }
]

Format output

[
    {
        "path": "/full/path/to/file.py"
    }
]

Custom config

cleer format --cleer python_path.to.my_file:my_cleer_instance path/to/file.py

Options

cleer format --log-level DEBUG --verbose --keep-excluded --keep-no-match path/to/dir/

• --log-level — Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL). Default: ERROR.
• --verbose — Include included, excluded, and invalidations in output.
• --keep-excluded — Include results for files that matched a group but were excluded.
• --keep-no-match — Include results for files that did not match any groups.

Config resolution

1. Custom instance from --cleer argument.
2. Default path clr:clr. A clr.py file in the current directory with a clr variable. The clr variable should be an instance of the Cleer.
3. Auto-generated default configuration. See Default Rules.

Configuration

Create a clr.py file in the root of your project. For the easiest start use the cleer_default_config generator to create a default config with some tweaks exposed.

"""clr.py"""

from cleer import cleer_default_config, Cleer


clr = Cleer(config=cleer_default_config(python_packages=["my_package"]))

For the most control, you can create you formatting config from scratch.

from cleer import *


clr = Cleer(
    config={
        "groups": [
            {
                "includes": [
                    "**/*.py"
                ],
                "excludes": [
                    "**/.venv*/**",
                    "**/venv*/**"
                ],
                "stages": [
                    {
                        "tokenizer": LineTokenizer(),
                        "formatters": [
                            TrailingWhitespaceFormatter()
                        ]
                    }
                ]
            }
        ]
    }
)

VSCode Integration

Auto-format on save with the Run On Save extension.

.vscode/settings.json:

{
    "emeraldwalk.runonsave": {
        "commands": [
            {
                "cmd": "./venv/bin/cleer format --log-level DEBUG ${file}"
            }
        ]
    }
}

Programmatic API

The CLI is a thin wrapper around the Cleer class. You can use it directly:

import pathlib

from cleer import Cleer, cleer_default_config


clr = Cleer(config=cleer_default_config(python_packages=["my_package"]))

# Inspect a string — path is only used for glob matching
result = clr.inspects("my_pkg/thing.py", "x = 1   \n")
# {
#     "path": "my_pkg/thing.py",
#     "included": [{"group": 0, "pattern": "**/*.py"}],
#     "excluded": [],
#     "invalidations": [],
#     "violations": [
#         {
#             "start_index": 0,
#             "length": 9,
#             "group": 0,
#             "stage": 0,
#             "formatter": 0,
#             "message": "Lines should not have any trailing whitespace."
#         }
#     ]
# }

# Inspect a file or directory
results = clr.inspect("my_pkg/")
# [{"path": ..., "violations": [...]}, ...]

# Format a string — returns result with formatted document
result = clr.formats("my_pkg/thing.py", "x = 1   \n")
# {
#     "path": "my_pkg/thing.py",
#     "included": [{"group": 0, "pattern": "**/*.py"}],
#     "excluded": [],
#     "invalidations": [],
#     "document": "x = 1\n"
# }

# Format a file or directory in place
results = clr.format("my_pkg/")
# [{"path": ..., "included": [...], "excluded": [], "invalidations": []}, ...]

Changelog

Changelog for cleer. All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.1.0a10] - 2026-08-13

Added

• many more example tests

Fixed

• **kwargs format

[0.1.0a9] - 2026-08-11

Fixed

• bad indent when formatting with |
• **kwargs format

[0.1.0a8] - 2026-08-10

Added

• handle unicode chars
• formatting for math and comparison operators.

Fixed

• comment indent being removed
• spaces before comments being removed.
• fixed glob matching to work on relative paths too.

[0.1.0a7] - 2026-08-10

Fixed

• remove pytokens dep

[0.1.0a6] - 2026-08-10

Fixed

• Bugs with paired punct giving violations when there aren't any.

[0.1.0a5] - 2026-08-10

Fixed

• Bugs with paired punct

[0.1.0a4] - 2026-08-10

Changed

Everything

[0.1.0a3] - 2026-07-20

Fixed

• missing glob.translate in python 3.11/12
• bad formatting on functions with "*" as an arg

[0.1.0a2] - 2026-07-20

Initial Release

[0.1.0a1] - 2024-02-18

Initial stub