Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Zac-HD/shed

`shed` canonicalises Python code. Shed your legacy, stop bikeshedding, and move on. Black++
https://github.com/Zac-HD/shed

Last synced: 3 months ago
JSON representation

`shed` canonicalises Python code. Shed your legacy, stop bikeshedding, and move on. Black++

Awesome Lists containing this project

README

        

# 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.3.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).