https://github.com/15r10nk/canonical-imports
canonical-imports follows your imports and finds out where the things you are importing are actually defined
https://github.com/15r10nk/canonical-imports
import linter python
Last synced: 8 months ago
JSON representation
canonical-imports follows your imports and finds out where the things you are importing are actually defined
- Host: GitHub
- URL: https://github.com/15r10nk/canonical-imports
- Owner: 15r10nk
- License: mit
- Created: 2024-01-03T14:35:19.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-07T20:42:26.000Z (8 months ago)
- Last Synced: 2025-04-07T21:40:34.404Z (8 months ago)
- Topics: import, linter, python
- Language: Python
- Homepage:
- Size: 17.6 KB
- Stars: 11
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
[](https://15r10nk.github.io/canonical-imports/)
[](https://pypi.org/project/canonical-imports/)
[](https://15r10nk.github.io/canonical-imports/contributing/#coverage)
[](https://github.com/sponsors/15r10nk)
Managing imports is difficult when the project grows in size. Functions and classes gets moved or renamed.
`canonical-imports` follows your imports and finds out where the things you are importing are actually defined.
It can change your imports which makes your code cleaner and maybe even faster.
## Installation
This project is currently only available for insiders, which mean that you can get access to it if you [sponsor](https://github.com/sponsors/15r10nk) me.
You should then have access to [this repository](https://github.com/15r10nk-insiders/canonical-imports).
You can install it with pip and the github url.
``` bash
pip install git+ssh://git@github.com/15r10nk-insiders/canonical-imports.git@insider
```
## Key Features
- follow imports to their definition and replace them.
- options to prevent the following of some types of imports (from public to private modules).
I will show you what it does with the following example:
``` python
# m/a.py
from ._core import helper
# m/_core.py
from ._utils import helper
# m/_utils.py
def helper():
print("some help")
```
`helper` was moved from `_core` to `_utils`
``` bash
canonical-imports -w m/a.py
```
changes `m/a.py` to:
``` python
# m/a.py
from ._utils import helper
```
## Usage
You can use `canonical-imports` from the command line to fix some files.
```bash
canonical-imports my_package/something.py
```
Use `canonical-imports --help` for more options.
### Options
canonical-imports follows all imports by default. `--no` can be used to prevent certain types of import changes.
- `--no public-private` prevents changing public imports into private imports like in the following:
``` diff
-from package.module import Thing
+from package.module._submodule import Thing
```
- `--no into-init` prevents following imports into `__init__.py` files.
Example:
``` python
# m/__init__.py
...
# m/a.py
from .b import f # <-- change to: from .q import f
# m/b.py
from .q import f # prevent changing to: from .q.c import f
# m/q/__init__.py
from .c import f
# m/q/c.py
def f():
pass
```
This rule does nothing if the import chain leaves the package `m.q` again (if `f` would be defined another package `m.x` for example).
This option might be useful if you do not use private module paths (with leading `_`).
## Issues
If you encounter any problems, please [report an issue](https://github.com/15r10nk/canonical-imports/issues) along with a detailed description.
## License
Distributed under the terms of the [MIT](http://opensource.org/licenses/MIT) license, "canonical-imports" is free and open source software.