| Name | ufmt JSON |
| Version |
2.8.0
JSON |
| download |
| home_page | None |
| Summary | Safe, atomic formatting with black and µsort |
| upload_time | 2024-10-25 06:21:57 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# µfmt
Safe, atomic formatting with [black][] and [µsort][]
[](https://pypi.org/project/ufmt)
[](https://ufmt.omnilib.dev)
[](https://ufmt.omnilib.dev/en/latest/changelog.html)
[](https://github.com/omnilib/ufmt/blob/master/LICENSE)
[](https://marketplace.visualstudio.com/items?itemName=omnilib.ufmt)
µ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:
```shell-session
$ 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:
```text
black==22.6.0
ufmt==2.0.0
usort==1.0.4
```
Usage
-----
To format one or more files or directories in place:
```shell-session
$ ufmt format <path> [<path> ...]
```
To validate files are formatted correctly, like for CI workflows:
```shell-session
$ ufmt check <path> [<path> ...]
```
To validate formatting and generate a diff of necessary changes:
```shell-session
$ ufmt diff <path> [<path> ...]
```
Integrations
------------
See the [user guide](https://ufmt.omnilib.dev/en/latest/guide.html#integrations)
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:
```yaml
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:
```yaml
- 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:
```json
"[python]": {
"editor.defaultFormatter": "omnilib.ufmt"
}
```
µfmt can automatically format when saving with the following settings:
```json
"[python]": {
"editor.defaultFormatter": "omnilib.ufmt",
"editor.formatOnSave": true
}
```
For more details, or to install the extension, see the Visual Studio Marketplace page:
[](https://marketplace.visualstudio.com/items?itemName=omnilib.ufmt)
[](vscode:extension/omnilib.ufmt)
License
-------
ufmt is copyright [Amethyst Reese](https://noswap.com), 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.
[black]: https://black.readthedocs.io
[µsort]: https://usort.readthedocs.io
[pre-commit]: https://pre-commit.com
Raw data
{
"_id": null,
"home_page": null,
"name": "ufmt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Amethyst Reese <amy@n7.gg>",
"download_url": "https://files.pythonhosted.org/packages/18/f8/c25e242a8e12062172dea4117859757a11339bbc39b1a3c7fb6a6de03bb2/ufmt-2.8.0.tar.gz",
"platform": null,
"description": "# \u00b5fmt\n\nSafe, atomic formatting with [black][] and [\u00b5sort][]\n\n[](https://pypi.org/project/ufmt)\n[](https://ufmt.omnilib.dev)\n[](https://ufmt.omnilib.dev/en/latest/changelog.html)\n[](https://github.com/omnilib/ufmt/blob/master/LICENSE)\n[](https://marketplace.visualstudio.com/items?itemName=omnilib.ufmt)\n\n\u00b5fmt is a safe, atomic code formatter for Python built on top of [black][] and [\u00b5sort][]:\n\n> Black makes code review faster by producing the smallest diffs possible. Blackened code looks the same regardless of the project you\u2019re reading.\n\n> \u03bcsort is a safe, minimal import sorter. Its primary goal is to make no \u201cdangerous\u201d changes to code, and to make no changes on code style.\n\n\u00b5fmt formats files in-memory, first with \u00b5sort and then with black, before writing any\nchanges back to disk. This enables a combined, atomic step in CI/CD workflows for\nchecking or formatting files, without any chance of conflict or intermediate changes\nbetween the import sorter and the code formatter.\n\n\nInstall\n-------\n\n\u00b5fmt requires Python 3.8 or newer. You can install it from PyPI:\n\n```shell-session\n$ pip install ufmt\n```\n\nIf you want to prevent unexpected formatting changes that can break your CI workflow,\nmake sure to pin your transitive dependencies\u2013including black, \u00b5sort, and \u00b5fmt\u2013to your\npreferred versions.\n\nIf you use `requirements.txt`, this might look like:\n\n```text\nblack==22.6.0\nufmt==2.0.0\nusort==1.0.4\n```\n\n\nUsage\n-----\n\nTo format one or more files or directories in place:\n\n```shell-session\n$ ufmt format <path> [<path> ...]\n```\n\nTo validate files are formatted correctly, like for CI workflows:\n\n```shell-session\n$ ufmt check <path> [<path> ...]\n```\n\nTo validate formatting and generate a diff of necessary changes:\n\n```shell-session\n$ ufmt diff <path> [<path> ...]\n```\n\n\nIntegrations\n------------\n\nSee the [user guide](https://ufmt.omnilib.dev/en/latest/guide.html#integrations)\nfor details on each integration.\n\n### GitHub Actions\n\n\u00b5fmt provides a GitHub Action that can be added to an existing workflow,\nor as a separate workflow or job, to enforce proper formatting in pull requests:\n\n```yaml\njobs:\n ufmt:\n runs-on: ubuntu-latest\n steps:\n - uses: omnilib/ufmt@action-v1\n with:\n path: <PATH TO CHECK>\n requirements: requirements-fmt.txt\n python-version: \"3.x\"\n```\n\n### pre-commit hook\n\n\u00b5fmt provides a [pre-commit][] hook. To format your diff before\nevery commit, add the following to your `.pre-commit-config.yaml` file:\n\n```yaml\n - repo: https://github.com/omnilib/ufmt\n rev: v2.0.0\n hooks:\n - id: ufmt\n additional_dependencies: \n - black == 22.6.0\n - usort == 1.0.4\n```\n\n### Visual Studio Code\n\n\u00b5fmt has an official VS Code extension to use \u00b5fmt as a formatter for Python files.\nOnce installed, \u00b5fmt can be set as the default formatter with the following settings:\n\n```json\n\"[python]\": {\n \"editor.defaultFormatter\": \"omnilib.ufmt\"\n}\n```\n\n\u00b5fmt can automatically format when saving with the following settings:\n\n```json\n\"[python]\": {\n \"editor.defaultFormatter\": \"omnilib.ufmt\",\n \"editor.formatOnSave\": true\n}\n```\n\nFor more details, or to install the extension, see the Visual Studio Marketplace page:\n\n[](https://marketplace.visualstudio.com/items?itemName=omnilib.ufmt)\n[](vscode:extension/omnilib.ufmt)\n\n\nLicense\n-------\n\nufmt is copyright [Amethyst Reese](https://noswap.com), and licensed under\nthe MIT license. I am providing code in this repository to you under an open\nsource license. This is my personal repository; the license you receive to\nmy code is from me and not from my employer. See the `LICENSE` file for details.\n\n\n[black]: https://black.readthedocs.io\n[\u00b5sort]: https://usort.readthedocs.io\n[pre-commit]: https://pre-commit.com\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Safe, atomic formatting with black and \u00b5sort",
"version": "2.8.0",
"project_urls": {
"Changelog": "https://ufmt.omnilib.dev/en/latest/changelog.html",
"Documentation": "https://ufmt.omnilib.dev",
"Github": "https://github.com/omnilib/ufmt"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "114b3f1b6f566b6cf70ccc5cba9a638fe4459f1e373c34d74df2e40e41871d70",
"md5": "8ef0fb9770502d01db530224a5277b63",
"sha256": "47a690811c576ebd3a0e30d77d43b65c84240e5c1611e5cb4a880bdd7f4507c1"
},
"downloads": -1,
"filename": "ufmt-2.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8ef0fb9770502d01db530224a5277b63",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 28268,
"upload_time": "2024-10-25T06:21:55",
"upload_time_iso_8601": "2024-10-25T06:21:55.822958Z",
"url": "https://files.pythonhosted.org/packages/11/4b/3f1b6f566b6cf70ccc5cba9a638fe4459f1e373c34d74df2e40e41871d70/ufmt-2.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "18f8c25e242a8e12062172dea4117859757a11339bbc39b1a3c7fb6a6de03bb2",
"md5": "ee8c77193ce0b62a9faa84f5cd623bea",
"sha256": "72c9502915497678de9aeab8aa18604890f14f869f7f378dd26e2878bde84f13"
},
"downloads": -1,
"filename": "ufmt-2.8.0.tar.gz",
"has_sig": false,
"md5_digest": "ee8c77193ce0b62a9faa84f5cd623bea",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24482,
"upload_time": "2024-10-25T06:21:57",
"upload_time_iso_8601": "2024-10-25T06:21:57.239644Z",
"url": "https://files.pythonhosted.org/packages/18/f8/c25e242a8e12062172dea4117859757a11339bbc39b1a3c7fb6a6de03bb2/ufmt-2.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-25 06:21:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "omnilib",
"github_project": "ufmt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ufmt"
}
