| Name | lazy_loader JSON |
| Version |
0.3
JSON |
| download |
| home_page | None |
| Summary | lazy_loader |
| upload_time | 2023-06-30 21:12:55 |
| maintainer | None |
| docs_url | None |
| author | Scientific Python Developers |
| requires_python | >=3.7 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://pypi.org/project/lazy_loader/)
[](https://github.com/scientific-python/lazy_loader/actions?query=workflow%3A%22test%22)
[](https://app.codecov.io/gh/scientific-python/lazy_loader/branch/main)
`lazy_loader` makes it easy to load subpackages and functions on demand.
## Motivation
1. Allow subpackages to be made visible to users without incurring import costs.
2. Allow external libraries to be imported only when used, improving import times.
For a more detailed discussion, see [the SPEC](https://scientific-python.org/specs/spec-0001/).
## Installation
```
pip install -U lazy_loader
```
## Usage
### Lazily load subpackages
Consider the `__init__.py` from [scikit-image](https://scikit-image.org):
```python
subpackages = [
...,
'filters',
...
]
import lazy_loader as lazy
__getattr__, __dir__, _ = lazy.attach(__name__, subpackages)
```
You can now do:
```python
import skimage as ski
ski.filters.gaussian(...)
```
The `filters` subpackages will only be loaded once accessed.
### Lazily load subpackages and functions
Consider `skimage/filters/__init__.py`:
```python
from ..util import lazy
__getattr__, __dir__, __all__ = lazy.attach(
__name__,
submodules=['rank'],
submod_attrs={
'_gaussian': ['gaussian', 'difference_of_gaussians'],
'edges': ['sobel', 'scharr', 'prewitt', 'roberts',
'laplace', 'farid']
}
)
```
The above is equivalent to:
```python
from . import rank
from ._gaussian import gaussian, difference_of_gaussians
from .edges import (sobel, scharr, prewitt, roberts,
laplace, farid)
```
Except that all subpackages (such as `rank`) and functions (such as `sobel`) are loaded upon access.
### Type checkers
Static type checkers and IDEs cannot infer type information from
lazily loaded imports. As a workaround you can load [type
stubs](https://mypy.readthedocs.io/en/stable/stubs.html) (`.pyi`
files) with `lazy.attach_stub`:
```python
import lazy_loader as lazy
__getattr__, __dir__, _ = lazy.attach_stub(__name__, "subpackages.pyi")
```
Note that, since imports are now defined in `.pyi` files, those
are not only necessary for type checking but also at runtime.
The SPEC [describes this workaround in more
detail](https://scientific-python.org/specs/spec-0001/#type-checkers).
### Early failure
With lazy loading, missing imports no longer fail upon loading the
library. During development and testing, you can set the `EAGER_IMPORT`
environment variable to disable lazy loading.
### External libraries
The `lazy.attach` function discussed above is used to set up package
internal imports.
Use `lazy.load` to lazily import external libraries:
```python
sp = lazy.load('scipy') # `sp` will only be loaded when accessed
sp.linalg.norm(...)
```
_Note that lazily importing *sub*packages,
i.e. `load('scipy.linalg')` will cause the package containing the
subpackage to be imported immediately; thus, this usage is
discouraged._
You can ask `lazy.load` to raise import errors as soon as it is called:
```
linalg = lazy.load('scipy.linalg', error_on_import=True)
```
Raw data
{
"_id": null,
"home_page": null,
"name": "lazy_loader",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Scientific Python Developers",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/0e/3a/1630a735bfdf9eb857a3b9a53317a1e1658ea97a1b4b39dcb0f71dae81f8/lazy_loader-0.3.tar.gz",
"platform": null,
"description": "[](https://pypi.org/project/lazy_loader/)\n[](https://github.com/scientific-python/lazy_loader/actions?query=workflow%3A%22test%22)\n[](https://app.codecov.io/gh/scientific-python/lazy_loader/branch/main)\n\n`lazy_loader` makes it easy to load subpackages and functions on demand.\n\n## Motivation\n\n1. Allow subpackages to be made visible to users without incurring import costs.\n2. Allow external libraries to be imported only when used, improving import times.\n\nFor a more detailed discussion, see [the SPEC](https://scientific-python.org/specs/spec-0001/).\n\n## Installation\n\n```\npip install -U lazy_loader\n```\n\n## Usage\n\n### Lazily load subpackages\n\nConsider the `__init__.py` from [scikit-image](https://scikit-image.org):\n\n```python\nsubpackages = [\n ...,\n 'filters',\n ...\n]\n\nimport lazy_loader as lazy\n__getattr__, __dir__, _ = lazy.attach(__name__, subpackages)\n```\n\nYou can now do:\n\n```python\nimport skimage as ski\nski.filters.gaussian(...)\n```\n\nThe `filters` subpackages will only be loaded once accessed.\n\n### Lazily load subpackages and functions\n\nConsider `skimage/filters/__init__.py`:\n\n```python\nfrom ..util import lazy\n\n__getattr__, __dir__, __all__ = lazy.attach(\n __name__,\n submodules=['rank'],\n submod_attrs={\n '_gaussian': ['gaussian', 'difference_of_gaussians'],\n 'edges': ['sobel', 'scharr', 'prewitt', 'roberts',\n 'laplace', 'farid']\n }\n)\n```\n\nThe above is equivalent to:\n\n```python\nfrom . import rank\nfrom ._gaussian import gaussian, difference_of_gaussians\nfrom .edges import (sobel, scharr, prewitt, roberts,\n laplace, farid)\n```\n\nExcept that all subpackages (such as `rank`) and functions (such as `sobel`) are loaded upon access.\n\n### Type checkers\n\nStatic type checkers and IDEs cannot infer type information from\nlazily loaded imports. As a workaround you can load [type\nstubs](https://mypy.readthedocs.io/en/stable/stubs.html) (`.pyi`\nfiles) with `lazy.attach_stub`:\n\n```python\nimport lazy_loader as lazy\n__getattr__, __dir__, _ = lazy.attach_stub(__name__, \"subpackages.pyi\")\n```\n\nNote that, since imports are now defined in `.pyi` files, those\nare not only necessary for type checking but also at runtime.\n\nThe SPEC [describes this workaround in more\ndetail](https://scientific-python.org/specs/spec-0001/#type-checkers).\n\n### Early failure\n\nWith lazy loading, missing imports no longer fail upon loading the\nlibrary. During development and testing, you can set the `EAGER_IMPORT`\nenvironment variable to disable lazy loading.\n\n### External libraries\n\nThe `lazy.attach` function discussed above is used to set up package\ninternal imports.\n\nUse `lazy.load` to lazily import external libraries:\n\n```python\nsp = lazy.load('scipy') # `sp` will only be loaded when accessed\nsp.linalg.norm(...)\n```\n\n_Note that lazily importing *sub*packages,\ni.e. `load('scipy.linalg')` will cause the package containing the\nsubpackage to be imported immediately; thus, this usage is\ndiscouraged._\n\nYou can ask `lazy.load` to raise import errors as soon as it is called:\n\n```\nlinalg = lazy.load('scipy.linalg', error_on_import=True)\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "lazy_loader",
"version": "0.3",
"project_urls": {
"Home": "https://scientific-python.org/specs/spec-0001/",
"Source": "https://github.com/scientific-python/lazy_loader"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a1c365b3814e155836acacf720e5be3b5757130346670ac454fee29d3eda1381",
"md5": "a14207a93562ded085306a505f14ba06",
"sha256": "1e9e76ee8631e264c62ce10006718e80b2cfc74340d17d1031e0f84af7478554"
},
"downloads": -1,
"filename": "lazy_loader-0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a14207a93562ded085306a505f14ba06",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 9087,
"upload_time": "2023-06-30T21:12:51",
"upload_time_iso_8601": "2023-06-30T21:12:51.090816Z",
"url": "https://files.pythonhosted.org/packages/a1/c3/65b3814e155836acacf720e5be3b5757130346670ac454fee29d3eda1381/lazy_loader-0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0e3a1630a735bfdf9eb857a3b9a53317a1e1658ea97a1b4b39dcb0f71dae81f8",
"md5": "6b0f19ab63de5d00b862325bbeca7ea7",
"sha256": "3b68898e34f5b2a29daaaac172c6555512d0f32074f147e2254e4a6d9d838f37"
},
"downloads": -1,
"filename": "lazy_loader-0.3.tar.gz",
"has_sig": false,
"md5_digest": "6b0f19ab63de5d00b862325bbeca7ea7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 12268,
"upload_time": "2023-06-30T21:12:55",
"upload_time_iso_8601": "2023-06-30T21:12:55.362823Z",
"url": "https://files.pythonhosted.org/packages/0e/3a/1630a735bfdf9eb857a3b9a53317a1e1658ea97a1b4b39dcb0f71dae81f8/lazy_loader-0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-30 21:12:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "scientific-python",
"github_project": "lazy_loader",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "lazy_loader"
}
