Proposed changes

resolves https://github.com/bwhmather/ssort/issues/24

solution is based from this url

https://pre-commit.com/#new-hooks

this also include following change/feature

• fix typo on readme
• precommit config
• example to use pre commit config
• github workflow to run pre commit
• tox env for pre-commit

added yaml ini file is formatted using

https://github.com/macisamuele/language-formatters-pre-commit-hooks

rst is checked using

https://github.com/Lucas-C/pre-commit-hooks-markup

github pre commit workflow is based from

https://github.com/pre-commit/action

isort and black pre commit config is added and modified from following urls

• https://pycqa.github.io/isort/docs/configuration/pre-commit.html
• https://black.readthedocs.io/en/stable/integrations/source_version_control.html?highlight=pre%20commit#version-control-integration

after merging this pr, the default rev value have to be changed to next version (0.10.1 or 0.11.0)

to test the pr add following hook to your pre commit config

- repo: https://github.com/rachmadaniHaryono/ssort
  rev: 545dc67985605706f8c26d5b596e7373d4ce9cf1
  hooks:
  - id: ssort

adjust rev value pr status

Types of changes

Put an x in the boxes that apply

• Bugfix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• [x] Documentation Update (if none of the other choices apply)

Checklist

• I have read the CONTRIBUTING doc
• Lint and unit tests pass locally with my changes
• I have added tests that prove my fix is effective or that my feature works
• [x] I have added necessary documentation (if appropriate)
• Any dependent changes have been merged and published in downstream modules

Further comments

this pr is modified from

https://github.com/appium/appium/blob/master/.github/PULL_REQUEST_TEMPLATE.md

Python 3.10 introduces pattern matching, which looks just as much of a pain to add support for as the walrus operator. Simply ignoring pattern matching is not an option as patterns introduce bindings which may be relied on later.

There are quite a few changes here so I'll try to break them down as best I can:

Generally simplified the _bindings and _requirements modules

The _bindings and _requirements modules both perform AST traversal so they share a lot of behavior. By extracting the common functionality of both modules to a new module, named _visitor, I was able to significantly reduce the size of both modules.

Improved overall performance

My initial intention was to utilize existing functionality from the standard library ast module to simplify the AST traversal done in both the _bindings and _requirements modules. However, after running some primitive benchmarks and realizing an over 20% reduction in performance I decided to scrap the idea. Instead, I put together the _visitors module and implemented a high speed alternative to the ast.NodeVisitor class. Swapping out the previously used functools.singledispatch AST traversal approach for the _visitor.NodeVisitor resulted in performance improvements in the 10%-15% range.

Fixes

While making the above changes I ran into a few existing issues which I fixed:

1. Fixed bindings not being discovered in return statements (test case).
2. Fixed bindings not being discovered in exception handler type expressions (test case).
3. Fixed dict not resolving requirements from its keys (test case)
4. Fixed augmented assignment not resolving requirements from its target (test case)
5. Fixed annotated assignment not resolving requirements from its annotations (test case)
6. Fixed functions and lambdas not resolving requirements from their arguments and annotations (test case)
7. Enabled walrus tests for Python 3.8 (test case)
8. Fixed with statement not resolving requirements from its optional_vars (test case)
9. Fixed for statement not resolving requirements from its target (test case)

Type annotations

Additionally, I added type annotations to the _bindings, _requirements, and _visitor modules.

Discover bindings made in the format spec of a format string.

Simple example illustrating how a variable can be bound inside a format spec:

>>> x
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'x' is not defined
>>>
>>> f"{3.1415:{(x := 0.3)}}"
'3.14'
>>>
>>> x
0.3

Proposed changes

related https://github.com/bwhmather/ssort/pull/25

• pre commit and its config
• pre commit github action ci config
• tox env rst_linter

goal of this pr

1. put all check on tox
2. put all formatter on pre commit
3. avoid cycles

hooks used

name | description | comment ---- | --- | --- trailing-whitespace | trims trailing whitespace | default end-of-file-fixer | ensures that a file is either empty, or ends with one newline | default check-yaml | checks yaml files for parseable syntax | recommended, to use with pretty-format-yaml check-added-large-files | prevents giant files from being committed | default pretty-format-yaml | hook sets a standard for formatting YAML files | recommended isort | python isort | recommended black | python black | recommended tox | run local tox | - tox-ini-fmt | Formats tox ini | recommended

check-yaml hook violate goal 1 but putting it on tox will violate goal 3

tox rst_linter only check for README.rst

pre commit github action skip black, isort and tox hooks to avoid duplicate with other github action

this pr wil not pass commit check because repo is not formatted by pre commit

after pr merge run pre-commit run --all-files and commit on single commit

to ignore that commit follow guide here https://github.com/ipython/ipython/blob/master/.git-blame-ignore-revs

related to this pr i found the comment from pre-commit

https://github.com/pre-commit/pre-commit/issues/2069

Types of changes

Put an x in the boxes that apply

• Bugfix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation Update (if none of the other choices apply)

Checklist

Put an x in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code.

• [x] I have read the CONTRIBUTING.md
• [x] Lint and unit tests pass locally with my changes
• I have added tests that prove my fix is effective or that my feature works
• I have added necessary documentation (if appropriate)
• Any dependent changes have been merged and published in downstream modules

Further comments

I ran ssort at the root of my project and it started sorting the files in my venv directory. (incidentally, this threw on venv/lib/python3.10/site-packages/blib2to3/pgen2/parse.py)

A proof of concept for a --reverse option as mentioned in #18. There is still some more work to be done here, but I wanted to open a draft to foster discussion on the approach I'm using here. Surprisingly, it seems this is a fairly straightforward addition.

Just tried ssort on a Windows 10 machine. I copied your example and saved it with CRLF line endings then ran ssort. It rewrote the line endings without removing the old ones (added a CR for each CRLF), here are some screenshots from Notepad++:

Initial file:

After:

Fixed signature of _on_wildcard_import_raise and _on_wildcard_import_ignore. Existing behavior causes a TypeError to be raised if a wildcard import is encountered and either on_wildcard_import="ignore" or on_wildcard_import="raise" is specified.

This gives better control over error reporting, and is more consistent with how other errors are handled. It makes it practical to fix some stupid bugs in the hook where attributes are being set the wrong way.

Added mypy checks and some general clean up to make the checks pass.

_utils.memoize_weak was giving mypy a hard time and, as far as I can tell, this function isn't actually used anywhere so I deleted it. @bwhmather, is this function needed?

Would it be feasible and desirable to extend ssort to support Jupyter notebooks? Jupyter supports running cells out of order, which makes it easy to have a notebook that won't run top to bottom. Using ssort to arrange the cells (and content within cells?) in an order that respects dependencies could be a helpful tool for resolving those issues.

Hi! Though I use ssort in pre-commit and CI I think it will be nice to have a possibility to set up ssort configuration in default pyproject.toml / setup.py files. There one can explicitly exclude some folders or files from ssorting, set the ordering and all other other possible cli-configs. Is it possible?

Before:

from dataclasses import dataclass


@dataclass
class User:
    id: int
    """User identifier."""

    email: str
    """E-mail address."""

    phone: str
    """Phone number in the international format."""

    age: int
    """Number of full years."""

After:

from dataclasses import dataclass


@dataclass
class User:
    id: int

    email: str

    phone: str

    age: int
    """User identifier."""
    """E-mail address."""
    """Phone number in the international format."""
    """Number of full years."""

There are two PEPs that describe such docstrings. Both of them were rejected.

• https://peps.python.org/pep-0224/
• https://peps.python.org/pep-0258/

I know that this is now a "real" docstring syntax but people still use it to document fields in their classes. Some tools support it as well (like sphinx).

It could be useful to recognise such docstrings and preserve their positions.

Escaping of paths for printing to the console is currently disabled on windows. At some point, we will need to untangle the byzantine rules for preparing strings to paste into the console and get this implemented.

The problem function: https://github.com/bwhmather/ssort/blob/f179281bfe7f56e203ba5a2ac55630855398f1e1/src/ssort/_utils.py#L52-L61

I just learned how to use git reset --hard (hardware guy, just learning Git) after fat fingering ssort without the file name... How about ssort . to explicitly say to process all files in the current file tree or maybe have a way to say all files in the current directory or all files in the current tree?

Topological ordering is good for understanding code but becomes less effective as the module becomes larger and dependency becomes more complex.

In such cases (and even in small modules), I find lexicographic (cos identifiers might also include digits) ordering much more fitting.