Automatically update `__all__` statements.
Project description
allways
Automatically update __all__
statements.
Installation
pip install allways
Command line interface
allways <file1.py> <file2.py> ...
As a pre-commit hook
See pre-commit for instructions.
Sample .pre-commit-config.yaml
- repo: https://github.com/tjsmart/allways
rev: v0.0.1
hooks:
- id: allways
Note: by default the pre-commit hook will run only against __init__.py
files.
What does it do?
Add __all__
statements to your python files
from ._foo import bar
from ._x import y as z
def foo():
...
becomes
from ._foo import bar
from ._x import y as z
def foo():
...
# allways: start
__all__ = [
"bar",
"foo",
"z",
]
# allways: end
Ignore private variables
from . import _foo
from . import bar
becomes
from . import _foo
from . import bar
# allways: start
__all__ = [
"bar",
]
# allways: end
Update pre-existing __all__
statements
from . import bar
from . import baz
# allways: start
__all__ = [
"bar",
"foo",
]
# allways: end
becomes
from . import bar
from . import baz
# allways: start
__all__ = [
"bar",
"baz",
]
# allways: end
Why?
the problem
I choose to organize python libraries with:
- PEP 561 compliance
- private module files, public (sub-)package folders
- using
__init__.py
to define the public interface of a (sub-)package
For example, I might layout my project as such:
pkg/
├── bar/
│ ├── _bar.py
│ └── __init__.py
├── _foo.py
├── __init__.py
└── py.typed
Contained in the files pkg/_foo.py
and pkg/bar/_bar.py
there will be some portion that I would like to expose publicly via pkg/__init__.py
and pkg/bar/__init__.py
, respectively.
For example, perhaps I would like to expose a function do_something
from the module file pkg/_foo.py
by adding the following line to pkg/__init__.py
:
from ._foo import do_something
And here is where the problem arises! (I know... a lot of setup...)
When a user of our package turns to use do_something
they will be slapped on the wrist by the type-checker.
pyright
output:
t.py:1:18 - error: "do_something" is not exported from module "pkg"
Import from "pkg._foo" instead (reportPrivateImportUsage)
mypy --strict
output:
t.py:1: error: Module "pkg" does not explicitly export attribute "do_something" [attr-defined]
And if you aren't concerned that users will have to ignore this type error, know that it get's worse! Language servers will not display any hint that the object pkg.do_something
exists. 😱
For small projects maintaining this by hand is no big deal. But for large projects with several contributors this becomes a complete wast of time! 😠
the solution
According to pyright documentation, a typed library can choose to explicitly re-export symbols by adding it to the __all__
of the corresponding module.
allways
mission is to automate the process of updating __all__
statements in __init__.py
files. 🤗
but also
My personal goal here is to contribute something to open source and write some more rust! 🦀
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Hashes for allways-0.0.1-py3-none-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 38d7437d498d30b90f05e715532d026b124dd8b4de9178367acdafa806dea50b |
|
MD5 | 7e7e9cb5d987f389aba9b4d43b884077 |
|
BLAKE2b-256 | 9d25f95c26ac5b0132f16aa80b07d4c1f0371dbd2a1d6ed06c1247b476dff80a |
Hashes for allways-0.0.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ff939707a9fbfb74df5b06617247ccfa9026e0789cce4b3035f2b3cb97716e52 |
|
MD5 | d1be61511f04730d501ef8beba60c1f5 |
|
BLAKE2b-256 | 55618b65fe12ad04b832c27015e4ade134f552d650d796295569a0b40fefb519 |
Hashes for allways-0.0.1-py3-none-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5a1d23ff0c025f8c7d3bf8163a170bd52458aa03933909f625119017f25ec06f |
|
MD5 | d7aa808753d99b4d75959860e1dfc1b8 |
|
BLAKE2b-256 | f3807f597450d56a82634b04a6b4d1a27ac4cbebd18b6e8f77901feef6fb795a |