# shed
`shed` canonicalises Python code. Shed your legacy, stop bikeshedding, and move on. Black++
## What does it do?
`shed` is the *maximally opinionated* autoformatting tool. It's *all about*
[convention over configuration](https://en.wikipedia.org/wiki/Convention_over_configuration),
and designed to be a single opinionated tool that fully canonicalises my
code - formatting, imports, updates, and every other fix I can possibly
automate.
There are no configuration options at all, but if the defaults aren't for you
that's OK - you can still use the underlying tools directly and get most of
the same effect... though you'll have to configure them yourself.
`shed` must either be run in a git repo to auto-detect the files to format,
or explicitly passed a list of files to format on the command-line.
## Features
`shed`...
- Runs [`ruff`](https://pypi.org/project/ruff/),
to remove unused imports and variables, upgrade code, sort imports, and more.
- Runs [`black`](https://pypi.org/project/black/),
with autodetected minimum version >= py38
- Formats code blocks in docstrings, markdown, and restructured text docs
(based on [`blacken-docs`](https://pypi.org/project/blacken-docs/)).
- If `shed --refactor`, also runs [`com2ann`](https://pypi.org/project/com2ann/)
and custom refactoring logic using [`libcst`](https://pypi.org/project/libcst/). See documentation for the codemods in [CODEMODS.md](CODEMODS.md)
The version detection logic is provided by `black`. Because `shed` supports the same
[versions of Python as upstream](https://devguide.python.org/#status-of-python-branches),
it assumes that the minimum version is Python 3.8.
If you run `shed` in a Git repository, the name of the root directory is assumed to be a
first-party import. [`src` layout](https://hynek.me/articles/testing-packaging/)
packages are also automatically detected, i.e. the `foo` in any paths like
`.../src/foo/__init__.py`.
### Jupyter Notebook support
We recommend [using `jupytext` to save your notebooks in `.py` or `.md` files](https://jupytext.readthedocs.io/en/latest/),
in which case `shed` supports them natively. For a quick-and-dirty workflow,
you can [use `nbqa shed notebook.ipynb`](https://nbqa.readthedocs.io/en/latest/readme.html) -
`nbqa` works for any linter or formatter.
## Using `shed` in your editor
We recommend [using `black` in your editor](https://black.readthedocs.io/en/stable/integrations/editors.html)
instead of `shed`, since it provides our core formatting logic and `shed`'s extra
smarts can be counterproductive while you're actively editing code - for example,
removing an "unused" import just after you add it!
Then, when you're done editing, you can run `shed` from the command-line, `pre-commit`
hooks, and your CI system.
## Using `shed` with pre-commit
If you use [pre-commit](https://pre-commit.com/), you can use it with Shed by
adding the following to your `.pre-commit-config.yaml`:
```yaml
minimum_pre_commit_version: '2.9.0'
repos:
- repo: https://github.com/Zac-HD/shed
rev: 2024.10.1
hooks:
- id: shed
# args: [--refactor, --py311-plus]
types_or: [python, pyi, markdown, rst]
```
This is often considerably faster for large projects, because `pre-commit`
can avoid running `shed` on unchanged files.
## See also
`shed` inherits `pyupgrade`'s careful approach to converting string formatting
code. If you want a more aggressive refactoring tool and don't mind checking
for breaking changes, [check out `flynt`](https://github.com/ikamensh/flynt).
For Django upgrades, see [`django-codemod`](https://github.com/browniebroke/django-codemod)
or [`django-upgrade`](https://github.com/adamchainz/django-upgrade).
The [`ssort` project](https://pypi.org/project/ssort/) sorts the contents of
python modules so that statements are placed after the things they depend on,
for easier navigation and consistency of design.
[`Semgrep` supports some autofixes](https://r2c.dev/blog/2022/autofixing-code-with-semgrep/#the-results),
with patterns for a wide variety of languages. This includes a variety of both
security and style checks, with manual inspection of results recommended.
## Changelog
Patch notes [can be found in `CHANGELOG.md`](https://github.com/Zac-HD/shed/blob/master/CHANGELOG.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/Zac-HD/shed",
"name": "shed",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Zac Hatfield-Dodds",
"author_email": "zac@zhd.dev",
"download_url": "https://files.pythonhosted.org/packages/53/dd/3808adbf116acd6556c4a7f328ff436a09cce8edc2d441e5821a2b329f07/shed-2024.10.1.tar.gz",
"platform": null,
"description": "# shed\n`shed` canonicalises Python code. Shed your legacy, stop bikeshedding, and move on. Black++\n\n## What does it do?\n`shed` is the *maximally opinionated* autoformatting tool. It's *all about*\n[convention over configuration](https://en.wikipedia.org/wiki/Convention_over_configuration),\nand designed to be a single opinionated tool that fully canonicalises my\ncode - formatting, imports, updates, and every other fix I can possibly\nautomate.\n\nThere are no configuration options at all, but if the defaults aren't for you\nthat's OK - you can still use the underlying tools directly and get most of\nthe same effect... though you'll have to configure them yourself.\n\n`shed` must either be run in a git repo to auto-detect the files to format,\nor explicitly passed a list of files to format on the command-line.\n\n## Features\n`shed`...\n\n- Runs [`ruff`](https://pypi.org/project/ruff/),\n to remove unused imports and variables, upgrade code, sort imports, and more.\n- Runs [`black`](https://pypi.org/project/black/),\n with autodetected minimum version >= py38\n- Formats code blocks in docstrings, markdown, and restructured text docs\n (based on [`blacken-docs`](https://pypi.org/project/blacken-docs/)).\n- If `shed --refactor`, also runs [`com2ann`](https://pypi.org/project/com2ann/)\n and custom refactoring logic using [`libcst`](https://pypi.org/project/libcst/). See documentation for the codemods in [CODEMODS.md](CODEMODS.md)\n\nThe version detection logic is provided by `black`. Because `shed` supports the same\n[versions of Python as upstream](https://devguide.python.org/#status-of-python-branches),\nit assumes that the minimum version is Python 3.8.\n\nIf you run `shed` in a Git repository, the name of the root directory is assumed to be a\nfirst-party import. [`src` layout](https://hynek.me/articles/testing-packaging/)\npackages are also automatically detected, i.e. the `foo` in any paths like\n`.../src/foo/__init__.py`.\n\n### Jupyter Notebook support\nWe recommend [using `jupytext` to save your notebooks in `.py` or `.md` files](https://jupytext.readthedocs.io/en/latest/),\nin which case `shed` supports them natively. For a quick-and-dirty workflow,\nyou can [use `nbqa shed notebook.ipynb`](https://nbqa.readthedocs.io/en/latest/readme.html) -\n`nbqa` works for any linter or formatter.\n\n## Using `shed` in your editor\nWe recommend [using `black` in your editor](https://black.readthedocs.io/en/stable/integrations/editors.html)\ninstead of `shed`, since it provides our core formatting logic and `shed`'s extra\nsmarts can be counterproductive while you're actively editing code - for example,\nremoving an \"unused\" import just after you add it!\n\nThen, when you're done editing, you can run `shed` from the command-line, `pre-commit`\nhooks, and your CI system.\n\n## Using `shed` with pre-commit\nIf you use [pre-commit](https://pre-commit.com/), you can use it with Shed by\nadding the following to your `.pre-commit-config.yaml`:\n\n```yaml\nminimum_pre_commit_version: '2.9.0'\nrepos:\n- repo: https://github.com/Zac-HD/shed\n rev: 2024.10.1\n hooks:\n - id: shed\n # args: [--refactor, --py311-plus]\n types_or: [python, pyi, markdown, rst]\n```\n\nThis is often considerably faster for large projects, because `pre-commit`\ncan avoid running `shed` on unchanged files.\n\n## See also\n`shed` inherits `pyupgrade`'s careful approach to converting string formatting\ncode. If you want a more aggressive refactoring tool and don't mind checking\nfor breaking changes, [check out `flynt`](https://github.com/ikamensh/flynt).\n\nFor Django upgrades, see [`django-codemod`](https://github.com/browniebroke/django-codemod)\nor [`django-upgrade`](https://github.com/adamchainz/django-upgrade).\n\nThe [`ssort` project](https://pypi.org/project/ssort/) sorts the contents of\npython modules so that statements are placed after the things they depend on,\nfor easier navigation and consistency of design.\n\n[`Semgrep` supports some autofixes](https://r2c.dev/blog/2022/autofixing-code-with-semgrep/#the-results),\nwith patterns for a wide variety of languages. This includes a variety of both\nsecurity and style checks, with manual inspection of results recommended.\n\n## Changelog\n\nPatch notes [can be found in `CHANGELOG.md`](https://github.com/Zac-HD/shed/blob/master/CHANGELOG.md).\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "`shed` canonicalises Python code.",
"version": "2024.10.1",
"project_urls": {
"Changelog": "https://github.com/Zac-HD/shed/blob/master/CHANGELOG.md",
"Homepage": "https://github.com/Zac-HD/shed",
"Source": "https://github.com/Zac-HD/shed/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5206d19e3bd9613ce5447f4c4aafd32d384e47a8de99ee2fcdede6e331109eab",
"md5": "524f9b3d7837b68380a57c0b84ef38d4",
"sha256": "fb8a76de5661f3aa33fca620660d8bc2cb16c6a83cc355a3e4eb2c138df01d96"
},
"downloads": -1,
"filename": "shed-2024.10.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "524f9b3d7837b68380a57c0b84ef38d4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 36297,
"upload_time": "2024-10-08T06:04:31",
"upload_time_iso_8601": "2024-10-08T06:04:31.388469Z",
"url": "https://files.pythonhosted.org/packages/52/06/d19e3bd9613ce5447f4c4aafd32d384e47a8de99ee2fcdede6e331109eab/shed-2024.10.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "53dd3808adbf116acd6556c4a7f328ff436a09cce8edc2d441e5821a2b329f07",
"md5": "11bf0d9a0eb5f3edd60565271140dce4",
"sha256": "094aa2f78fd5e307ba7ac31ee65caf501e552dca3ec70632234f8af62ca0c761"
},
"downloads": -1,
"filename": "shed-2024.10.1.tar.gz",
"has_sig": false,
"md5_digest": "11bf0d9a0eb5f3edd60565271140dce4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 39486,
"upload_time": "2024-10-08T06:04:32",
"upload_time_iso_8601": "2024-10-08T06:04:32.505193Z",
"url": "https://files.pythonhosted.org/packages/53/dd/3808adbf116acd6556c4a7f328ff436a09cce8edc2d441e5821a2b329f07/shed-2024.10.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-08 06:04:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Zac-HD",
"github_project": "shed",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "shed"
}
JSON
