========
zimports
========
Reformats Python imports so that they can pass flake8-import-order. This is
roughly:
* one import per line
* alphabetically sorted, with stylistic options for how dots, case sensitivity,
and dotted names are sorted
* grouped by builtin / external library / current application (also
stylistically controllable)
* unused imports removed, using pyflakes to match "unused import" warnings
to actual lines of code
* duplicate imports removed (note this does not yet include duplicate symbol
names against different imports)
* no star imports (e.g. ``from <foo> import *``); these are rewritten as
explicit names, by importing all the names from each target module and then
removing all the unused names
* support for TYPE_CHECKING import blocks.
The program currently bolts itself on top of `flake8-import-order
<https://github.com/PyCQA/flake8-import-order/>`_, in order to reuse the import
classification and sorting styles that tool provides. Without options given,
the script will look directly for a ``setup.cfg`` file with a ``[flake8]``
section and will consume flake8-import-order parameters ``"application-import-
names"``, ``"application-package-names"``, and ``"import-order-style"``, to
sort imports exactly as this linter then expects to find them. All of the
single-line import styles, e.g. google, cryptography, pycharm, should just
work.
Special classifications can be given to imports, as either a " # noqa" comment
indicating the import should not be removed, and optionally
the comment " # noqa nosort" which will place the import into a special
"don't sort" category, placing all of the "nosort" imports in the order
they originally appeared, grouped after all the sorted imports. This can
be used for special situations where a few imports have to be in a certain
order against each other (SQLAlchemy has two lines like this at the moment).
The application also does not affect imports that are inside of conditionals
or defs, or otherwise indented in any way, with the exception of TYPE_CHECKING
imports. This is also the behavior of
flake8-import-order; only imports in column zero of the source file are
counted, although imports that are on lines below other definitions are
counted, which are moved up to the top section of the source file.
.. note:: This application runs in **Python 3 only**. It can reformat
imports for Python 2 code as well but internally it uses library
and language features only available in Python 3.
zzzeek why are you writing one of these, there are a dozen pep8 import fixers
=============================================================================
I've just gone through a whole bunch. I need one that:
* works directly with flake8-import-order so we are guaranteed to have a match
* has shell capability, not only a plugin for vim or sublime text (Python Fix
Imports, gratis)
* Removes unused imports, not just reformats them (importanize)
* Reformats imports, not just removes unused ones (autoflake)
* Doesn't miss removing an import that isn't used just because it's on a
multiline import (autoflake)
* Breaks up *all* imports into individual lines, not just if the line is >80 char
(importanize)
* Is still pretty simple (we're a bit beyond our original "extremely" simple
baseline, because all problems are ultimately not that simple) because (since
pyflakes and now flake8-import-order do most of the hard work) this is an
extremely simple job, there's (still) no need for a giant application here.
But what about... isort ??
--------------------------
Since I developed zimports some years ago and now have it on all my projects,
isort has come out and is widely becoming accepted as the de-facto import
sorter, because it's actually super nice and has tons of features. It popped up
turned on by default in my vscode IDE and it's under pycqa, it's clearly the
winning tool in this space.
So I would *like* to use isort, and I've tried it out. I was able to get it 99%
equivalent to how we sort our imports now, with the exception of a weird
relative import issue that still wouldn't compare against
``flake8-import-order`` (it seemed like lexical sorting wasn't working
correctly). Maybe we can get that little part working, but that's not the main
issue.
The bigger shortcoming was IIUC it, like "importanize" mentioned previously,
just reformats the imports that are present. It won't remove unused imports,
nor does it have any ability to expand ``import *`` into individual imports,
since it isn't looking at the rest of the code. zimports actually hangs on top of
``flake8`` so that we can remove unused imports and it also uses ``flake8``
output along with a module import path in order to expand out "*" imports.
I use this feature *all the time* when I type out test scripts for SQLAlchemy,
I just start with ``from sqlalchemy import *`` and have zimports clean it all up.
Maybe there would be a way to keep zimports for that part, and then use isort
for the actual sorting. But then I'm still just using zimports, and while isort
definitely does a better job at finding imports to sort (it does them inside
method bodies, inside of cython files, wow), it's not really worth it right now
for me to change everything when I still have to maintain zimports anyway.
TL;DR; yes go use isort, I have no desire to support zimports for other people!
:) zimports does a few things that I personally like a
lot, especially removing unused imports which is totally essential for my
use cases.
Usage
=====
The script can run without any configuration, options are as follows::
$ zimports --help
usage: zimports [-h] [-m APPLICATION_IMPORT_NAMES]
[-p APPLICATION_PACKAGE_NAMES] [--style STYLE] [--multi-imports]
[-k] [-kt] [--heuristic-unused HEURISTIC_UNUSED] [--statsonly]
[-e] [--diff] [--stdout]
filename [filename ...]
positional arguments:
filename Python filename(s) or directories
optional arguments:
-h, --help show this help message and exit
-m APPLICATION_IMPORT_NAMES, --application-import-names APPLICATION_IMPORT_NAMES
comma separated list of names that should be
considered local to the application. reads from
[flake8] application-import-names by default.
-p APPLICATION_PACKAGE_NAMES, --application-package-names APPLICATION_PACKAGE_NAMES
comma separated list of names that should be
considered local to the organization. reads from
[flake8] application-package-names by default.
--style STYLE import order styling, reads from [flake8] import-
order-style by default, or defaults to 'google'
--multi-imports If set, multiple imports can exist on one line
-k, --keep-unused keep unused imports even though detected as unused.
Implies keep-unused-type-checking
-kt, --keep-unused-type-checking
keep unused imports even though detected as unused in
type checking blocks. zimports does not detect type usage
in comments or when used as string
--heuristic-unused HEURISTIC_UNUSED
Remove unused imports only if number of imports is
less than <HEURISTIC_UNUSED> percent of the total
lines of code. Ignored in type checking blocks
--statsonly don't write or display anything except the file stats
-e, --expand-stars Expand star imports into the names in the actual
module, which can then have unused names removed.
Requires modules can be imported
--diff don't modify files, just dump out diffs
--stdout dump file output to stdout
Configuration is currently broken up between consumption of flake8 parameters
from ``setup.cfg``, and then additional zimports parameters in
``pyproject.toml`` (as of version 0.5.0) - unification of these two files will
be in a future release, possibly when flake8 adds toml support::
# setup.cfg
[flake8]
enable-extensions = G
ignore =
A003,
E203,E305,E711,E712,E721,E722,E741,
F841,
N801,N802,N806,
W503,W504
import-order-style = google
application-import-names = sqlalchemy,test
# pyproject.toml, integrated with black
[tool.black]
line-length = 79
target-version = ['py37']
[tool.zimports]
black-line-length = 79
keep-unused-type-checking = true
# other options:
# multi-imports = true
# keep-unused = true
Then, a typical run on a mostly clean source tree looks like::
$ zimports lib/
[Unchanged] lib/sqlalchemy/inspection.py (in 0.0058 sec)
[Unchanged] lib/sqlalchemy/log.py (in 0.0221 sec)
...
[Unchanged] lib/sqlalchemy/orm/attributes.py (in 0.2152 sec)
[Unchanged] lib/sqlalchemy/orm/base.py (in 0.0363 sec)
[Writing] lib/sqlalchemy/orm/relationships.py ([2% of lines are imports] [source +0L/-2L] [3 imports removed in 0.3287 sec])
[Unchanged] lib/sqlalchemy/orm/strategies.py (in 0.2237 sec)
The program has two general modes of usage. One is that of day-to-day usage
for an application that already has clean imports. Running zimports on the
source files of such an application should produce no changes, except for
whatever source files were recently edited, and may have some changes to
imports that need to be placed into the correct order. This usage model is
similar to that of `Black <https://github.com/ambv/black>`_, where you can run
"zimports ." and it will find whatever files need adjusting and leave the rest
alone.
The other mode of usage is that of the up-front cleaning up of an application
that has un- organized imports. In this mode of usage, the goal is to get
the source files to be cleaned up so that ``zimports`` can be run straight
without any modifications to the file needed, including that all necessary
imports are either used locally or marked as not to be removed.
Problems that can occur during this phase are that some imports are unused and
should be removed, while other imports that are apparently unused are still in
fact imported by other parts of the program. Another issue is that changing
the ordering of imports in complex cases may cause the application to no longer
run due to the creation of unresolvable import cycles. Finally, some
programs have use of ``import *``, pulling in a large list of names for which
an unknown portion of them are needed by the application. The options
``--keep-unused``, ``--heuristic-unused`` and ``--expand-stars`` are
provided to assist in working through these issues until the code can be
fully reformatted such that running ``zimports`` no longer produces changes.
The issue of apparently unused imports that are externally imported can be
prominent in some applications. In order to allow imports that aren't locally
used to remain in the source file, symbols that are part of
``__all__`` will not be removed, as will imports that are followed by a `` #
noqa`` comment. Either of these techniques should be applied to imports that
are used from other modules but not otherwise referenced within the immediate
source file. For the less common case that a few imports really need a very
specific import order for things to work, those imports can be followed by a ``
# noqa nosort`` comment that will add these lines to a special group at the end
of all imports, where they will not be removed and their order relative to each
other will be maintained.
The program does currently require that you pass it at least one file or
directory name as an argument. It also does not have the file caching feature
that Black has, which can allow it to only look at files that have changed
since the last run. The plan is to have it check that it's inside a git
repository where it will run through files to be committed if no filenames are
given.
Usage as a ``git`` hook
=======================
``zimports`` can be used with the pre-commit_ git hooks framework. To add
the plugin, add the following to your ``.pre-commit-config.yaml``. Note
the ``rev:`` attribute refers to a git tag or revision number of
zimports to be used, such as ``"master"`` or ``"0.1.3"``:
.. code-block:: yaml
repos:
- repo: https://github.com/sqlalchemyorg/zimports/
rev: v0.4.5
hooks:
- id: zimports
.. _pre-commit: https://pre-commit.com/
Raw data
{
"_id": null,
"home_page": "https://github.com/sqlalchemyorg/zimports",
"name": "zimports",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Mike Bayer",
"author_email": "mike_mp@zzzcomputing.com",
"download_url": "https://files.pythonhosted.org/packages/fd/5b/295a2b599307f2b08b1436b5fd4c544aa43ee0915d7485b237094f14d8a4/zimports-0.6.1.tar.gz",
"platform": null,
"description": "========\nzimports\n========\n\nReformats Python imports so that they can pass flake8-import-order. This is\nroughly:\n\n* one import per line\n\n* alphabetically sorted, with stylistic options for how dots, case sensitivity,\n and dotted names are sorted\n\n* grouped by builtin / external library / current application (also\n stylistically controllable)\n\n* unused imports removed, using pyflakes to match \"unused import\" warnings\n to actual lines of code\n\n* duplicate imports removed (note this does not yet include duplicate symbol\n names against different imports)\n\n* no star imports (e.g. ``from <foo> import *``); these are rewritten as\n explicit names, by importing all the names from each target module and then\n removing all the unused names\n\n* support for TYPE_CHECKING import blocks.\n\nThe program currently bolts itself on top of `flake8-import-order\n<https://github.com/PyCQA/flake8-import-order/>`_, in order to reuse the import\nclassification and sorting styles that tool provides. Without options given,\nthe script will look directly for a ``setup.cfg`` file with a ``[flake8]``\nsection and will consume flake8-import-order parameters ``\"application-import-\nnames\"``, ``\"application-package-names\"``, and ``\"import-order-style\"``, to\nsort imports exactly as this linter then expects to find them. All of the\nsingle-line import styles, e.g. google, cryptography, pycharm, should just\nwork.\n\nSpecial classifications can be given to imports, as either a \" # noqa\" comment\nindicating the import should not be removed, and optionally\nthe comment \" # noqa nosort\" which will place the import into a special\n\"don't sort\" category, placing all of the \"nosort\" imports in the order\nthey originally appeared, grouped after all the sorted imports. This can\nbe used for special situations where a few imports have to be in a certain\norder against each other (SQLAlchemy has two lines like this at the moment).\n\nThe application also does not affect imports that are inside of conditionals\nor defs, or otherwise indented in any way, with the exception of TYPE_CHECKING\nimports. This is also the behavior of\nflake8-import-order; only imports in column zero of the source file are\ncounted, although imports that are on lines below other definitions are\ncounted, which are moved up to the top section of the source file.\n\n.. note:: This application runs in **Python 3 only**. It can reformat\n imports for Python 2 code as well but internally it uses library\n and language features only available in Python 3.\n\n\nzzzeek why are you writing one of these, there are a dozen pep8 import fixers\n=============================================================================\n\nI've just gone through a whole bunch. I need one that:\n\n* works directly with flake8-import-order so we are guaranteed to have a match\n\n* has shell capability, not only a plugin for vim or sublime text (Python Fix\n Imports, gratis)\n\n* Removes unused imports, not just reformats them (importanize)\n\n* Reformats imports, not just removes unused ones (autoflake)\n\n* Doesn't miss removing an import that isn't used just because it's on a\n multiline import (autoflake)\n\n* Breaks up *all* imports into individual lines, not just if the line is >80 char\n (importanize)\n\n* Is still pretty simple (we're a bit beyond our original \"extremely\" simple\n baseline, because all problems are ultimately not that simple) because (since\n pyflakes and now flake8-import-order do most of the hard work) this is an\n extremely simple job, there's (still) no need for a giant application here.\n\nBut what about... isort ??\n--------------------------\n\nSince I developed zimports some years ago and now have it on all my projects,\nisort has come out and is widely becoming accepted as the de-facto import\nsorter, because it's actually super nice and has tons of features. It popped up\nturned on by default in my vscode IDE and it's under pycqa, it's clearly the\nwinning tool in this space.\n\nSo I would *like* to use isort, and I've tried it out. I was able to get it 99%\nequivalent to how we sort our imports now, with the exception of a weird\nrelative import issue that still wouldn't compare against\n``flake8-import-order`` (it seemed like lexical sorting wasn't working\ncorrectly). Maybe we can get that little part working, but that's not the main\nissue.\n\nThe bigger shortcoming was IIUC it, like \"importanize\" mentioned previously,\njust reformats the imports that are present. It won't remove unused imports,\nnor does it have any ability to expand ``import *`` into individual imports,\nsince it isn't looking at the rest of the code. zimports actually hangs on top of\n``flake8`` so that we can remove unused imports and it also uses ``flake8``\noutput along with a module import path in order to expand out \"*\" imports.\nI use this feature *all the time* when I type out test scripts for SQLAlchemy,\nI just start with ``from sqlalchemy import *`` and have zimports clean it all up.\n\nMaybe there would be a way to keep zimports for that part, and then use isort\nfor the actual sorting. But then I'm still just using zimports, and while isort\ndefinitely does a better job at finding imports to sort (it does them inside\nmethod bodies, inside of cython files, wow), it's not really worth it right now\nfor me to change everything when I still have to maintain zimports anyway.\n\nTL;DR; yes go use isort, I have no desire to support zimports for other people!\n:) zimports does a few things that I personally like a\nlot, especially removing unused imports which is totally essential for my\nuse cases.\n\nUsage\n=====\n\nThe script can run without any configuration, options are as follows::\n\n $ zimports --help\n usage: zimports [-h] [-m APPLICATION_IMPORT_NAMES]\n [-p APPLICATION_PACKAGE_NAMES] [--style STYLE] [--multi-imports]\n [-k] [-kt] [--heuristic-unused HEURISTIC_UNUSED] [--statsonly]\n [-e] [--diff] [--stdout]\n filename [filename ...]\n\n positional arguments:\n filename Python filename(s) or directories\n\n optional arguments:\n -h, --help show this help message and exit\n -m APPLICATION_IMPORT_NAMES, --application-import-names APPLICATION_IMPORT_NAMES\n comma separated list of names that should be\n considered local to the application. reads from\n [flake8] application-import-names by default.\n -p APPLICATION_PACKAGE_NAMES, --application-package-names APPLICATION_PACKAGE_NAMES\n comma separated list of names that should be\n considered local to the organization. reads from\n [flake8] application-package-names by default.\n --style STYLE import order styling, reads from [flake8] import-\n order-style by default, or defaults to 'google'\n --multi-imports If set, multiple imports can exist on one line\n -k, --keep-unused keep unused imports even though detected as unused.\n Implies keep-unused-type-checking\n -kt, --keep-unused-type-checking\n keep unused imports even though detected as unused in\n type checking blocks. zimports does not detect type usage\n in comments or when used as string\n --heuristic-unused HEURISTIC_UNUSED\n Remove unused imports only if number of imports is\n less than <HEURISTIC_UNUSED> percent of the total\n lines of code. Ignored in type checking blocks\n --statsonly don't write or display anything except the file stats\n -e, --expand-stars Expand star imports into the names in the actual\n module, which can then have unused names removed.\n Requires modules can be imported\n --diff don't modify files, just dump out diffs\n --stdout dump file output to stdout\n\nConfiguration is currently broken up between consumption of flake8 parameters\nfrom ``setup.cfg``, and then additional zimports parameters in\n``pyproject.toml`` (as of version 0.5.0) - unification of these two files will\nbe in a future release, possibly when flake8 adds toml support::\n\n # setup.cfg\n\n [flake8]\n enable-extensions = G\n ignore =\n A003,\n E203,E305,E711,E712,E721,E722,E741,\n F841,\n N801,N802,N806,\n W503,W504\n import-order-style = google\n application-import-names = sqlalchemy,test\n\n # pyproject.toml, integrated with black\n\n [tool.black]\n line-length = 79\n target-version = ['py37']\n\n\n [tool.zimports]\n black-line-length = 79\n keep-unused-type-checking = true\n\n # other options:\n # multi-imports = true\n # keep-unused = true\n\nThen, a typical run on a mostly clean source tree looks like::\n\n $ zimports lib/\n [Unchanged] lib/sqlalchemy/inspection.py (in 0.0058 sec)\n [Unchanged] lib/sqlalchemy/log.py (in 0.0221 sec)\n\n ...\n\n [Unchanged] lib/sqlalchemy/orm/attributes.py (in 0.2152 sec)\n [Unchanged] lib/sqlalchemy/orm/base.py (in 0.0363 sec)\n [Writing] lib/sqlalchemy/orm/relationships.py ([2% of lines are imports] [source +0L/-2L] [3 imports removed in 0.3287 sec])\n [Unchanged] lib/sqlalchemy/orm/strategies.py (in 0.2237 sec)\n\nThe program has two general modes of usage. One is that of day-to-day usage\nfor an application that already has clean imports. Running zimports on the\nsource files of such an application should produce no changes, except for\nwhatever source files were recently edited, and may have some changes to\nimports that need to be placed into the correct order. This usage model is\nsimilar to that of `Black <https://github.com/ambv/black>`_, where you can run\n\"zimports .\" and it will find whatever files need adjusting and leave the rest\nalone.\n\nThe other mode of usage is that of the up-front cleaning up of an application\nthat has un- organized imports. In this mode of usage, the goal is to get\nthe source files to be cleaned up so that ``zimports`` can be run straight\nwithout any modifications to the file needed, including that all necessary\nimports are either used locally or marked as not to be removed.\n\nProblems that can occur during this phase are that some imports are unused and\nshould be removed, while other imports that are apparently unused are still in\nfact imported by other parts of the program. Another issue is that changing\nthe ordering of imports in complex cases may cause the application to no longer\nrun due to the creation of unresolvable import cycles. Finally, some\nprograms have use of ``import *``, pulling in a large list of names for which\nan unknown portion of them are needed by the application. The options\n``--keep-unused``, ``--heuristic-unused`` and ``--expand-stars`` are\nprovided to assist in working through these issues until the code can be\nfully reformatted such that running ``zimports`` no longer produces changes.\n\nThe issue of apparently unused imports that are externally imported can be\nprominent in some applications. In order to allow imports that aren't locally\nused to remain in the source file, symbols that are part of\n``__all__`` will not be removed, as will imports that are followed by a `` #\nnoqa`` comment. Either of these techniques should be applied to imports that\nare used from other modules but not otherwise referenced within the immediate\nsource file. For the less common case that a few imports really need a very\nspecific import order for things to work, those imports can be followed by a ``\n# noqa nosort`` comment that will add these lines to a special group at the end\nof all imports, where they will not be removed and their order relative to each\nother will be maintained.\n\nThe program does currently require that you pass it at least one file or\ndirectory name as an argument. It also does not have the file caching feature\nthat Black has, which can allow it to only look at files that have changed\nsince the last run. The plan is to have it check that it's inside a git\nrepository where it will run through files to be committed if no filenames are\ngiven.\n\nUsage as a ``git`` hook\n=======================\n\n``zimports`` can be used with the pre-commit_ git hooks framework. To add\nthe plugin, add the following to your ``.pre-commit-config.yaml``. Note\nthe ``rev:`` attribute refers to a git tag or revision number of\nzimports to be used, such as ``\"master\"`` or ``\"0.1.3\"``:\n\n.. code-block:: yaml\n\n repos:\n - repo: https://github.com/sqlalchemyorg/zimports/\n rev: v0.4.5\n hooks:\n - id: zimports\n\n\n.. _pre-commit: https://pre-commit.com/\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Yet another import fixing tool",
"version": "0.6.1",
"project_urls": {
"Homepage": "https://github.com/sqlalchemyorg/zimports",
"Issue Tracker": "https://github.com/sqlalchemyorg/zimports/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4afec509625030533b7870b95d9c4f58ca7e3a7e839143b028f22f09e185c379",
"md5": "f92c57699c4c50ec2690383e238601ad",
"sha256": "d2483cfcae4b0783a2573b93fd186a5694e5b8ddf5bf110317a72dd9e72dfbfe"
},
"downloads": -1,
"filename": "zimports-0.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f92c57699c4c50ec2690383e238601ad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 20479,
"upload_time": "2023-08-17T06:09:31",
"upload_time_iso_8601": "2023-08-17T06:09:31.315637Z",
"url": "https://files.pythonhosted.org/packages/4a/fe/c509625030533b7870b95d9c4f58ca7e3a7e839143b028f22f09e185c379/zimports-0.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fd5b295a2b599307f2b08b1436b5fd4c544aa43ee0915d7485b237094f14d8a4",
"md5": "92147ac09e776a106913b3955897437a",
"sha256": "8c801a653cd3aaea7b8347c42237bd32705bcb0be5d1987a16d8df56cc31baab"
},
"downloads": -1,
"filename": "zimports-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "92147ac09e776a106913b3955897437a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 56247,
"upload_time": "2023-08-17T06:09:33",
"upload_time_iso_8601": "2023-08-17T06:09:33.431472Z",
"url": "https://files.pythonhosted.org/packages/fd/5b/295a2b599307f2b08b1436b5fd4c544aa43ee0915d7485b237094f14d8a4/zimports-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-17 06:09:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sqlalchemyorg",
"github_project": "zimports",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "zimports"
}
JSON
