Skip to content

omnilib/ufmt

Folders and files

NameName
Last commit message
Last commit date

Latest commit

75dd45a · Nov 19, 2024
Oct 25, 2024
Jul 22, 2024
Oct 25, 2024
May 23, 2022
Sep 5, 2021
Mar 12, 2023
Sep 17, 2021
Oct 19, 2023
Oct 25, 2024
Oct 11, 2024
Aug 24, 2022
Feb 22, 2024
Feb 12, 2024
Sep 2, 2024
Nov 19, 2024

Repository files navigation

µfmt

Safe, atomic formatting with black and µsort

version documentation changelog license vscode extension

µfmt is a safe, atomic code formatter for Python built on top of black and µsort:

Black makes code review faster by producing the smallest diffs possible. Blackened code looks the same regardless of the project you’re reading.

μsort is a safe, minimal import sorter. Its primary goal is to make no “dangerous” changes to code, and to make no changes on code style.

µfmt formats files in-memory, first with µsort and then with black, before writing any changes back to disk. This enables a combined, atomic step in CI/CD workflows for checking or formatting files, without any chance of conflict or intermediate changes between the import sorter and the code formatter.

Install

µfmt requires Python 3.8 or newer. You can install it from PyPI:

$ pip install ufmt

If you want to prevent unexpected formatting changes that can break your CI workflow, make sure to pin your transitive dependencies–including black, µsort, and µfmt–to your preferred versions.

If you use requirements.txt, this might look like:

black==22.6.0
ufmt==2.0.0
usort==1.0.4

Usage

To format one or more files or directories in place:

$ ufmt format <path> [<path> ...]

To validate files are formatted correctly, like for CI workflows:

$ ufmt check <path> [<path> ...]

To validate formatting and generate a diff of necessary changes:

$ ufmt diff <path> [<path> ...]

Integrations

See the user guide for details on each integration.

GitHub Actions

µfmt provides a GitHub Action that can be added to an existing workflow, or as a separate workflow or job, to enforce proper formatting in pull requests:

jobs:
  ufmt:
    runs-on: ubuntu-latest
    steps:
      - uses: omnilib/ufmt@action-v1
        with:
          path: <PATH TO CHECK>
          requirements: requirements-fmt.txt
          python-version: "3.x"

pre-commit hook

µfmt provides a pre-commit hook. To format your diff before every commit, add the following to your .pre-commit-config.yaml file:

  - repo: https://github.com/omnilib/ufmt
    rev: v2.0.0
    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:

VS Code extension marketplace Install VS Code extension now

License

ufmt is copyright Amethyst Reese, and licensed under the MIT license. I am providing code in this repository to you under an open source license. This is my personal repository; the license you receive to my code is from me and not from my employer. See the LICENSE file for details.