| Name | module-hygiene JSON |
| Version |
0.3.4
JSON |
| download |
| home_page | |
| Summary | Keep your Python modules (and packages, and any other namespaces) clean and tidy! |
| upload_time | 2023-01-21 21:41:45 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | |
| keywords |
hygiene
module
namespace
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Module Hygiene
_Simple tools to help with Python namespace hygiene!_
## Description
This is an opinionated project! I prefer Python modules to only
include what's necessary for users. If I'm in an IDE and type
`from module import <TAB>`, I want only API-level elements to
be available! Many Python projects use a leading underscore to
specify _private_-like objects and modules. Still, it's sometimes
nice to keep things simple without multiple `_module` definitions
in a package.
This package is my solution! It currently provides a single function,
`cleanup`, which returns code to delete all `locals` which are not
in a provided "export list".
## Usage
See the example usage below. Note that we need to import `T` to add
a proper typed signature for the function `square`. Unfortunately,
this means that `T` is also available to anyone who imports
this module.
By default, `cleanup` assumes
the name of the module's export list is `'__export__'`. If you
want to choose a different export list name, pass that name as a
`str` to cleanup!
```python
"""module.py
A python module which exports a single function, `square`.
"""
from hygiene import cleanup
from typing import T
__export__ = [
"square",
]
def square(x: T) -> T:
"""Returns the square of x!"""
return x ** 2
if __name__ != "__main__":
cleanup()
```
This `cleanup` approach will likely change how you write Python modules.
If you need a Python package throughout your module, like `numpy`,
you likely `import numpy as np` at the top of your module, and use `np`
in various functions throughout the module. If you `cleanup` at the end of
the module, your code will break on execution because `np` will no longer
exist!
If you choose to use `cleanup`, then you will need to `import` modules
**at the function level**. Personally, I like this better anyways! Every
dependency is right next to where it's used. One major downside of this
approach is you need to parse your source code for `import` statements
to track all dependencies.
```python
"""another.py
Another module which exports a single function, `abssqrt`!
"""
from hygiene import cleanup
from typing import T
# Don't do this!
# from numpy import abs, sqrt
__export_list__ = [
"abssqrt",
]
def abssqrt(x: T) -> T:
"""Returns the square root of the absolute value of `x`!"""
from numpy import abs, sqrt
return sqrt(abs(x))
if __name__ != "__main__":
cleanup(export = __export_list__)
```
Raw data
{
"_id": null,
"home_page": "",
"name": "module-hygiene",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "hygiene,module,namespace",
"author": "",
"author_email": "Joe Carpinelli <jdcarpinelli@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/5e/52/6db0c4f00ab450524cdfaf2f70a4efdf36078f01a1b9e5048d1e820eaf48/module_hygiene-0.3.4.tar.gz",
"platform": null,
"description": "# Module Hygiene\n_Simple tools to help with Python namespace hygiene!_\n\n\n## Description\n\nThis is an opinionated project! I prefer Python modules to only \ninclude what's necessary for users. If I'm in an IDE and type\n`from module import <TAB>`, I want only API-level elements to \nbe available! Many Python projects use a leading underscore to\nspecify _private_-like objects and modules. Still, it's sometimes\nnice to keep things simple without multiple `_module` definitions\nin a package.\n\nThis package is my solution! It currently provides a single function,\n`cleanup`, which returns code to delete all `locals` which are not \nin a provided \"export list\".\n\n## Usage\n\nSee the example usage below. Note that we need to import `T` to add\na proper typed signature for the function `square`. Unfortunately,\nthis means that `T` is also available to anyone who imports \nthis module. \n\nBy default, `cleanup` assumes \nthe name of the module's export list is `'__export__'`. If you \nwant to choose a different export list name, pass that name as a \n`str` to cleanup!\n\n```python\n\"\"\"module.py\n\nA python module which exports a single function, `square`.\n\"\"\"\n\nfrom hygiene import cleanup\nfrom typing import T \n\n__export__ = [\n \"square\",\n]\n\ndef square(x: T) -> T:\n \"\"\"Returns the square of x!\"\"\"\n return x ** 2\n\nif __name__ != \"__main__\":\n cleanup()\n```\n\nThis `cleanup` approach will likely change how you write Python modules.\nIf you need a Python package throughout your module, like `numpy`, \nyou likely `import numpy as np` at the top of your module, and use `np`\nin various functions throughout the module. If you `cleanup` at the end of \nthe module, your code will break on execution because `np` will no longer \nexist! \n\nIf you choose to use `cleanup`, then you will need to `import` modules \n**at the function level**. Personally, I like this better anyways! Every \ndependency is right next to where it's used. One major downside of this \napproach is you need to parse your source code for `import` statements \nto track all dependencies. \n\n```python\n\"\"\"another.py\n\nAnother module which exports a single function, `abssqrt`!\n\"\"\"\n\nfrom hygiene import cleanup\nfrom typing import T\n\n# Don't do this!\n# from numpy import abs, sqrt\n\n__export_list__ = [\n \"abssqrt\",\n]\n\ndef abssqrt(x: T) -> T:\n \"\"\"Returns the square root of the absolute value of `x`!\"\"\"\n from numpy import abs, sqrt\n return sqrt(abs(x))\n\nif __name__ != \"__main__\":\n cleanup(export = __export_list__)\n```\n",
"bugtrack_url": null,
"license": "",
"summary": "Keep your Python modules (and packages, and any other namespaces) clean and tidy!",
"version": "0.3.4",
"split_keywords": [
"hygiene",
"module",
"namespace"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "270bba7b3491998a5a10068a8078e0703b1ff7f65b5465a0d8a3cf63343e23fc",
"md5": "fac3b9b53707f99315ecb32a79c88cb2",
"sha256": "f655d775ffea74a06c00205c07bdff02dae903081e8192bf5c11288ae5ac7dc7"
},
"downloads": -1,
"filename": "module_hygiene-0.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fac3b9b53707f99315ecb32a79c88cb2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 4521,
"upload_time": "2023-01-21T21:41:43",
"upload_time_iso_8601": "2023-01-21T21:41:43.584570Z",
"url": "https://files.pythonhosted.org/packages/27/0b/ba7b3491998a5a10068a8078e0703b1ff7f65b5465a0d8a3cf63343e23fc/module_hygiene-0.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5e526db0c4f00ab450524cdfaf2f70a4efdf36078f01a1b9e5048d1e820eaf48",
"md5": "5d57df63470eb4b65667c29d7c29a639",
"sha256": "cfd3582e26f5cfbb2deeffcb4f34e27d5ce34dea18fad785c0cc6b8734bc2cbe"
},
"downloads": -1,
"filename": "module_hygiene-0.3.4.tar.gz",
"has_sig": false,
"md5_digest": "5d57df63470eb4b65667c29d7c29a639",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 4004,
"upload_time": "2023-01-21T21:41:45",
"upload_time_iso_8601": "2023-01-21T21:41:45.171725Z",
"url": "https://files.pythonhosted.org/packages/5e/52/6db0c4f00ab450524cdfaf2f70a4efdf36078f01a1b9e5048d1e820eaf48/module_hygiene-0.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-21 21:41:45",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "module-hygiene"
}
