{"id":3307,"library":"ufmt","title":"ufmt: Safe, Atomic Formatting with Black and µsort","description":"ufmt (pronounced \"micro-fmt\") is a safe, atomic code formatter for Python, built on top of the popular `black` formatter and `µsort` import sorter. It combines their functionality into a single, atomic step, ensuring consistent code style and import order without intermediate conflicts. Currently at version 2.9.1, it requires Python 3.10 or newer and maintains an active release cadence.","status":"active","version":"2.9.1","language":"en","source_language":"en","source_url":"https://github.com/omnilib/ufmt","tags":["formatter","linter","code quality","black","usort","autofix","python3"],"install":[{"cmd":"pip install ufmt","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for code formatting. It is highly recommended to pin its version for consistent CI results.","package":"black"},{"reason":"Core dependency for import sorting. It is highly recommended to pin its version for consistent CI results.","package":"usort"}],"imports":[{"note":"High-level API for formatting multiple files or directories recursively.","symbol":"ufmt_paths","correct":"from ufmt import ufmt_paths"},{"note":"High-level API for formatting a single file.","symbol":"ufmt_file","correct":"from ufmt import ufmt_file"}],"quickstart":{"code":"import os\nfrom pathlib import Path\nfrom ufmt import ufmt_file\nfrom black import Mode, TargetVersion\nfrom usort import Config\n\ndef main():\n    # Create a dummy Python file\n    dummy_content = (\n        \"import os, sys\\n\\ndef my_func ( param1,  param2 ) :\\n    \\\"\\\"\\\"A docstring.\\\"\\\"\\\"\\n    return  param1  + param2\\n\"\n    )\n    dummy_file = Path(\"temp_module.py\")\n    dummy_file.write_text(dummy_content)\n\n    print(f\"Original content of {dummy_file.name}:\\n---\\n{dummy_content.strip()}\\n---\")\n\n    # Define black and usort configs (optional, ufmt can detect from pyproject.toml)\n    # For this example, we provide minimal configs\n    black_config = Mode(target_versions={TargetVersion.PY310})\n    usort_config = Config()\n\n    # Format the file using the ufmt API\n    result = ufmt_file(\n        path=dummy_file,\n        black_config=black_config,\n        usort_config=usort_config,\n        return_content=True\n    )\n\n    if result.error:\n        print(f\"Error formatting {dummy_file.name}: {result.error}\")\n    elif result.changed:\n        print(f\"Formatted content of {dummy_file.name}:\\n---\\n{result.after.decode().strip()}\\n---\")\n    else:\n        print(f\"{dummy_file.name} was already formatted correctly.\\n---\\n{result.after.decode().strip()}\\n---\")\n\n    # Clean up the dummy file\n    dummy_file.unlink()\n\nif __name__ == \"__main__\":\n    main()","lang":"python","description":"This quickstart demonstrates how to use the `ufmt_file` API to programmatically format a Python file. It creates a temporary file, formats it with `ufmt`, prints the original and formatted content, and then cleans up the temporary file. For simple command-line usage, run `ufmt format <path>` in your terminal."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer.","message":"ufmt v2.0.0 dropped support for Python 3.6. v2.2.0 further dropped support for Python 3.7. Users must be on Python 3.10 or newer (as of 2.9.1).","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update calls to `ufmt_file()` and `ufmt_paths()` to use keyword arguments (e.g., `ufmt_file(path=my_path)`).","message":"The `ufmt_file` and `ufmt_paths` API functions now require keyword arguments for all parameters.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Migrate from `ufmt_string` to `ufmt_bytes` for programmatic formatting of string-like content.","message":"The `ufmt_string` function was deprecated in v2.0.0 and will be removed in v3.0. Use `ufmt_bytes` instead for formatting raw byte content.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Pin `black==X.Y.Z`, `usort==A.B.C`, and `ufmt==P.Q.R` in your dependency declarations.","message":"For stable and reproducible CI workflows, always pin the versions of `ufmt`, `black`, and `usort` in your `requirements.txt` or `pyproject.toml` to prevent unexpected formatting changes introduced by newer versions of these transitive dependencies.","severity":"gotcha","affected_versions":"all"},{"fix":"Upgrade to `ufmt` version 2.1.0 or newer, or set the environment variable `LIBCST_PARSER_TYPE=native` before running `ufmt`.","message":"Prior to v2.1.0, `ufmt` could fail to format Python 3.10+ `match case` statements due to `µsort`'s reliance on `LibCST`. This was fixed by enabling `LibCST`'s native parser by default. If using older `ufmt` versions, an `LIBCST_PARSER_TYPE=native` environment variable was required.","severity":"gotcha","affected_versions":"<2.1.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}