/flake8-alphabetize

Python style checker for import statements, __all__ lists and exception lists, implemented as a flake8 plugin

Primary LanguagePythonMIT No AttributionMIT-0

Flake8 Alphabetize

Alphabetize is a Flake8 plugin for checking the order of import statements, the __all__ list and except lists. It is designed to work well with the Black formatting tool, in that Black never alters the Abstract Syntax Tree (AST), while Alphabetize is only interested in the AST, and so the two tools never conflict. In the spirit of Black, Alphabetize is an 'uncompromising import style checker' in that the style can't be configured, there's just one style (see below for the rules).

Alphabetise is released under the MIT-0 licence. It is tested on Python 3.7+.

Build Status

  1. Create a virtual environment: python3 -m venv venv
  2. Activate it: source venv/bin/activate
  1. Install: pip install flake8-alphabetize

Say we have a Python file myfile.py:

from datetime import time, date

print(time(9, 39), date(2021, 4, 11))

by running the command flake8 we'll get:

myfile.py:1:1: AZ200 Imported names are in the wrong order. Should be date, time

We can tell Alphabetize what the package name is, and then it'll know that its imports should be in a group at the bottom of the imports. Here's an example:

import uuid

from myapp import myfunc

print(uuid.UUID4(), myfunc())

by running the command flake8 --application-names myapp we won't get any errors.

As you use Flake8 in the normal way, Alphabetize will report errors using the following codes:

Error Codes
Code Error Type
AZ100 Import statements are in the wrong order
AZ200 The names in the import from are in the wrong order
AZ300 Two import from statements must be combined.
AZ400 The names in the __all__ are in the wrong order
AZ500 The names in the exception handler list are in the wrong order

Alphabetize follows the Black formatter's uncompromising approach and so there's only one configuration option which is application-names. This is a comma-separated list of top-level, package names that are to be treated as application imports, eg. 'myapp'. Since Alphabetize is a Flake8 plugin, this configuration option is set using Flake8 configuration.

Alphabetize can be easily configured to run in your existing pre-commit hooks, as an additional dependency of Flake8:

repos:
   - repo: https://github.com/pycqa/flake8
     rev: 6.0.0
     hooks:
      - id: flake8
        additional_dependencies: ['flake8-alphabetize']

Here are the ordering rules that Alphabetize follows:

  1. The special case from __future__ import comes first.
  2. Imports from the standard library come next, followed by third party imports, followed by application imports.
  3. Relative imports are assumed to be application imports.
  4. The standard library group has import statements first (in alphabetical order), followed by from import statements (in alphabetical order).
  5. The third party group is further grouped by library name. Then each library subgroup has import statements first (in alphabetical order), followed by from import statements (in alphabetical order).
  6. The application group is further grouped by import level, with absolute imports first and then relative imports of increasing level. Within each level, the imports should be ordered by library name. Then each library subgroup has import statements first (in alphabetical order), followed by from import statements (in alphabetical order).
  7. from import statements for the same library must be combined.
  8. Alphabetize only looks at imports at the module level, any imports within the code are ignored.

Run tox to run the tests.

  • Install tox: pip install tox
  • Run tox: tox

It might be worth running the OpenSSF Scorecard:

sudo docker run -e GITHUB_AUTH_TOKEN=<auth_token> gcr.io/openssf/scorecard:stable \
--repo=github.com/tlocke/flake8-alphabetize

Run tox to make sure all tests pass, then update the release notes, then do:

git tag -a x.y.z -m "version x.y.z"
rm -r dist
python -m build
twine upload dist/*

Version 0.0.21, 2023-04-13

  • Fixed a bug where it crashes on qualified names in an exception list.

Version 0.0.20, 2023-04-02

  • Check the ordering of except handler lists.

Version 0.0.19, 2022-11-24

  • Make Alphabetize compatible with Flake8 6.0.0

Version 0.0.18, 2022-10-29

  • Fix bug where sub-packages (eg. collections.abc) aren't recognised as being part of the standard library for versions of Python >= 3.10.

Version 0.0.17, 2021-11-17

  • Handle the case of an __all__ being a tuple.

Version 0.0.16, 2021-07-26

  • Don't perform any import order checks if there are multiple imports on a line, as this will be reported by Flake8. Once the Flake8 error has been fixed, checks can continue.

Version 0.0.15, 2021-06-17

  • Fix bug where the --application-names command line option failed with a comma-separated list.

Version 0.0.14, 2021-04-20

  • Fix bug where from . import logging appears in message as from .None import logging.

Version 0.0.13, 2021-04-20

  • Fix bug where it fails on a relative import such as from . import logging.

Version 0.0.12, 2021-04-12

  • Check the order of the elements of __all__.

Version 0.0.11, 2021-04-11

  • Order application imports by import level, absolute imports at the top.

Version 0.0.10, 2021-04-11

  • Fix bug where potentially fails with > 2 imports.

Version 0.0.9, 2021-04-11

  • There's a clash of option names, so now application imports can now be identified by setting the application-names configuration option.

Version 0.0.8, 2021-04-11

  • Application imports can now be identified by setting the application-package-names configuration option.

Version 0.0.7, 2021-04-10

  • Import of __future__. Should always be first.

Version 0.0.6, 2021-04-10

  • Third party libraries should be grouped by top-level name.

Version 0.0.5, 2021-04-10

  • Take into account whether a module is in the standard library or not.

Version 0.0.4, 2021-04-10

  • Make entry point AZ instead of ALP.

Version 0.0.3, 2021-04-10

  • Check the order within from import statements.

Version 0.0.2, 2021-04-09

  • Partially support from import statements.

Version 0.0.1, 2021-04-09

  • Now partially supports import statements.

Version 0.0.0, 2021-04-09

  • Initial release. Doesn't do much at this stage.