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.2
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.2-py3-none-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9eb1a4a2961626528228ac996af881c2a61e7677bd4a4a54256a034ed52d08e6 |
|
MD5 | 293f7cd7264bb739696d8fb26ea6871d |
|
BLAKE2b-256 | 7c6c7fa01789224252d3a4565c143457e22d1d7f3b724c311dc232e66f5b35d4 |
Hashes for allways-0.0.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ba52e22664573340df21ec7f7b3cc67f0989c602cfc5cf3e9cfb68da251467a4 |
|
MD5 | 7c2a0ac2d751463e3d82342fd9cbd15e |
|
BLAKE2b-256 | 4df574ea88db2c7942bf8a597163f23de3569def8ca0fdff4507dd036bddcda8 |
Hashes for allways-0.0.2-py3-none-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 14ec4c847b53cfdd034c12b7c9d03a8a49bcac1f186bbf86b022c66188b6709a |
|
MD5 | 6893a4c8fa56e3a81aa3c00fc6b64966 |
|
BLAKE2b-256 | 3377b52ea6e6fa8043f2ad2b379aae5ac5845e92c5e7868bc633acf30cb6007a |