cercis 0.1.0

A more configurable Python code formatter

Cercis

Cercis /ˈsɜːrsɪs/ is a Python code formatter that is more configurable than Black (a popular Python code formatter).

Cercis is also a name of a deciduous tree that boasts vibrant pink to purple-hued flowers, which bloom in early spring.

This code repository is forked from and directly inspired by Black. The original license of Black is included in this repository (see LICENSE_ORIGINAL).

1. Motivations

While we like the idea of auto-formatting and making code readable, we take issue with some style choices and the lack of configurability of the Black formatter. We acknowledge that people have different style preferences, and we believe this is totally OK.

Therefore, Cercis aims at providing some configurability beyond Black's limited offering.

2. Installation and usage

2.1. Installation

Cercis can be installed by running pip install cercis. It requires Python 3.7+ to run. If you want to format Jupyter Notebooks, install with pip install "cercis[jupyter]".

2.2. Usage

2.2.1. Command line usage

To get started right away with sensible defaults:

cercis {source_file_or_directory}

You can run Cercis as a package if running it as a script doesn't work:

python -m cercis {source_file_or_directory}

The commands above reformat entire file(s) in place.

2.2.2. As pre-commit hook

To format Python files (.py), put the following into your .pre-commit-config.yaml file. Remember to replace <VERSION> with your version of this tool (such as v0.1.0):

- repo: https://github.com/jsh9/cercis
  rev: <VERSION>
  hooks:
    - id: cercis

To format Jupyter notebooks (.ipynb), put the following into your .pre-commit-config.yaml file:

- repo: https://github.com/jsh9/cercis
  rev: <VERSION>
  hooks:
    - id: cercis-jupyter

See pre-commit for more instructions.

3. The code style

The code style in Cercis is largely consistent with the style of of Black.

The differences are summarized below:

3.1. Extra indentation of at function definition

For this example input:

def very_important_function(template: str, *variables, file: os.PathLike, engine: str, header: bool = True, debug: bool = False):
    """Applies `variables` to the `template` and writes to `file`."""
    with open(file, 'w') as f:
        ...

Black formats it as this:

def very_important_function(
    template: str,
    *variables,
    file: os.PathLike,
    engine: str,
    header: bool = True,
    debug: bool = False,
):
    """Applies `variables` to the `template` and writes to `file`."""
    with open(file, "w") as f:
        ...

while Cercis formats it as:

def very_important_function(
        template: str,
        *variables,
        file: os.PathLike,
        engine: str,
        header: bool = True,
        debug: bool = False,
):
    """Applies `variables` to the `template` and writes to `file`."""
    with open(file, "w") as f:
        ...

We choose to indent an extra 4 spaces because it adds a clear visual separation between the function name and the argument list. Not adding extra indentation is also called out as wrong in the the official PEP8 style guide.

4. Configuration

Cercis is able to read project-specific default values for its command line options from a pyproject.toml file. This is especially useful for specifying custom --include and --exclude/--force-exclude/--extend-exclude patterns for your project.

Change Log

[0.1.0] - 2023-04-30

This is the initial version that branches away from Black (commit: e712e4)

Changed

• The default indentation within a function definition (when line wrap happens) is now 8 spaces. (Black's default is 4, which is not PEP8-compatible)
• Updated README, because cercis now branches away from Black

Added

• A configurable option (function-definition-extra-indent) is added instead of enforcing 8 spaces for everyone