User Guide

Configuration

All configuration for µfmt is done via the pyproject.toml file. This is the same file that is used for configuring black and µsort.

Specifying options requires adding them to the tool.ufmt namespace, following this example:

[tool.ufmt]
excludes = [...]

Options available are described as follows:

excludes: List[str]

Optional list of supplemental patterns of file paths to exclude from formatting. Each element must be a string following “gitignore” style matching rules. These excludes will be combined with the contents of the project root’s .gitignore file, and any file or directory path that matches any of these patterns will not be formatted.

pyproject.toml

[tool.ufmt]
excludes = [
    "fizz.py",
    "foo/",
]

This configuration would ignore the following paths when formatting a project:

• fizz.py

• bar/fizz.py

• foo/buzz.py

• foo/bar/baz.py

Integrations

µfmt supports integrations with the following tools and services:

• GitHub Actions

• pre-commit

• Visual Studio Code

GitHub Actions

µfmt can be run as part of a project’s existing Actions workflow, adding the following snippet to the steps section of a job:

steps:
  - uses: omnilib/ufmt@action-v1
    with:
      path: <PATH TO CHECK>

This can also be added as a standalone workflow. If a setup-python step is not already used, the python-version input must be specified:

.github/workflows/ufmt.yml

name: "µfmt"
on:
  push:
    branches:
      - main
  pull_request:
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Check formatting
        uses: omnilib/ufmt@action-v1
        with:
          path: <PATH TO CHECK>
          python-version: "3.x"

For consistent and predictable behavior in CI, it is recommended to pin your version of black and µsort. These can be individually configured in the workflow (see Options), but prefer using a requirements file with pinned versions, and the µfmt action can install those dependencies if they aren’t already installed by a previous step:

requirements-fmt.txt

black==22.6.0
usort==1.0.4

.github/workflows/ufmt.yml

steps:
  - uses: omnilib/ufmt@action-v1
    with:
      path: <PATH TO CHECK>
      requirements: requirements-fmt.txt

Options

The following inputs are supported to change the way the Action is performed, and must be specified as part of the with section of the job step:

path(required)

One or more paths (relative to the repository root) that should be checked.

requirements

Path to a requirements file (relative to repo root) that should be installed before checking formatting. Any pinned version of black, µsort, or µfmt will be used, unless otherwise overridden by version, black-version, or usort-version, or incompatible with the version of µfmt requested.

version

The version of µfmt to install and use when checking formatting.

Defaults to installing the latest version, or whatever version is already installed by previous steps in the workflow.

black-version

The version of black to install and use when checking formatting.

Defaults to installing the latest version, or whatever version is already installed by previous steps in the workflow.

python-version

When specified, the Github actions/setup-python action will be triggered, with the given version string as the desired version of Python to use. Using "3.x" is recommended, to run µfmt using the latest stable release of Python.

See the setup-python advanced usage for supported values.

usort-version

The version of µsort to install and use when checking formatting.

Defaults to installing the latest version, or whatever version is already installed by previous steps in the workflow.

pre-commit

µfmt can format your project automatically before every commit as part of a project’s pre-commit hook. Add the following to the .pre-commit-config.yaml file:

- repo: https://github.com/omnilib/ufmt
  rev: v2.0.0
  hooks:
    - id: ufmt

additional_dependencies

Preferred versions of black and µsort should be provided for consistent results. By default, µfmt will format using the latest versions of black and µsort.

- repo: https://github.com/omnilib/ufmt
  hooks:
    - id: ufmt
      additional_dependencies:
        - black == 22.6.0
        - usort == 1.0.4

Visual Studio Code

µfmt has an official VS Code extension to use µfmt as a formatter for Python files. Once installed, µfmt can be set as the default formatter with the following settings:

"[python]": {
  "editor.defaultFormatter": "omnilib.ufmt"
}

µfmt can automatically format when saving with the following settings:

"[python]": {
  "editor.defaultFormatter": "omnilib.ufmt",
  "editor.formatOnSave": true
}

For more details, or to install the extension, see the Visual Studio Marketplace page: