| Name | necessary JSON |
| Version |
0.4.3
JSON |
| download |
| home_page | |
| Summary | Python package to enforce optional dependencies |
| upload_time | 2023-06-27 18:17:37 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | Apache-2.0 |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Necessary
Python package that can be used to enforce optional dependencies are installed when a module is imported. Necessary stands for "Now Ensures Correct Existence of Select Software, or Add Resource Yourself!"
Necessary is available on [PyPI](https://pypi.org/project/necessary/), and can be installed with the following command:
```bash
pip install necessary
```
## How to Use
### As Context Manager
Simply use `necessary.necessary` to get a context manager import a module.
```python
from necessary import necessary
with necessary('torch'):
# this will raise a nicely written error if
# torch is not installed
import torch
```
If you want to just soft fail when a necessary module is not available (that is, have necessary return `False`), use `soft`:
```python
try:
# assuming torch is not installed
necessary('torch')
except ImportError:
out = necessary('torch', soft=True)
assert out is False
```
If you want to request a minimum version, use Python's requirements syntax:
```python
with necessary('torch>=1.12.0'):
# this will raise an error if
# torch is not installed or if
# the installed version is less than 0.12.0
import torch
```
You can also check multiple packages in the same `necessary` call, or combine multiple requirements:
```python
with necessary(['torch>=1.12.0', 'numpy>=1.20,<1.25']):
# this will raise an error if torch >= 1.12.0 or numpy are not installed
import torch
import numpy
```
Finally, we can customize the message that is raised if a necessary module is not installed; use `{module_name}` and `{module_version}` to insert the module name and version respectively.
```python
with necessary('torch', message='I am missing {module_name}/{module_version}'):
import torch
```
### As Function or Class Decorator
You can also use `necessary` as a function or class decorator:
```python
from necessary import Necessary
# decorating a function
@Necessary('torch')
def my_function():
import torch
# decorating a class
@Necessary('torch')
class MyClass:
def __init__(self):
import torch
```
All of the same functionality is available in the decorator form as in the context manager form.
Raw data
{
"_id": null,
"home_page": "",
"name": "necessary",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "",
"author_email": "Luca Soldaini <luca@soldaini.net>",
"download_url": "https://files.pythonhosted.org/packages/cc/d5/01b84f230f7d08d3aebd82937ffefd279b0ca8ab2d03cf3f41e8c6222e25/necessary-0.4.3.tar.gz",
"platform": null,
"description": "# Necessary\n\nPython package that can be used to enforce optional dependencies are installed when a module is imported. Necessary stands for \"Now Ensures Correct Existence of Select Software, or Add Resource Yourself!\"\n\nNecessary is available on [PyPI](https://pypi.org/project/necessary/), and can be installed with the following command:\n\n```bash\npip install necessary\n```\n\n## How to Use\n\n### As Context Manager\n\nSimply use `necessary.necessary` to get a context manager import a module.\n\n```python\nfrom necessary import necessary\n\nwith necessary('torch'):\n # this will raise a nicely written error if\n # torch is not installed\n import torch\n```\n\nIf you want to just soft fail when a necessary module is not available (that is, have necessary return `False`), use `soft`:\n\n```python\ntry:\n # assuming torch is not installed\n necessary('torch')\nexcept ImportError:\n out = necessary('torch', soft=True)\n assert out is False\n```\n\nIf you want to request a minimum version, use Python's requirements syntax:\n\n```python\nwith necessary('torch>=1.12.0'):\n # this will raise an error if\n # torch is not installed or if\n # the installed version is less than 0.12.0\n import torch\n```\n\nYou can also check multiple packages in the same `necessary` call, or combine multiple requirements:\n\n```python\nwith necessary(['torch>=1.12.0', 'numpy>=1.20,<1.25']):\n # this will raise an error if torch >= 1.12.0 or numpy are not installed\n import torch\n import numpy\n```\n\nFinally, we can customize the message that is raised if a necessary module is not installed; use `{module_name}` and `{module_version}` to insert the module name and version respectively.\n\n```python\nwith necessary('torch', message='I am missing {module_name}/{module_version}'):\n import torch\n```\n\n### As Function or Class Decorator\n\nYou can also use `necessary` as a function or class decorator:\n\n```python\n\nfrom necessary import Necessary\n\n# decorating a function\n@Necessary('torch')\ndef my_function():\n import torch\n\n# decorating a class\n@Necessary('torch')\nclass MyClass:\n def __init__(self):\n import torch\n```\n\nAll of the same functionality is available in the decorator form as in the context manager form.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Python package to enforce optional dependencies",
"version": "0.4.3",
"project_urls": {
"Homepage": "https://github.com/soldni/necessary",
"Source": "https://github.com/soldni/necessary",
"Tracker": "https://github.com/soldni/necessary/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d2fd7b5a09553f81e7ff5bae6af151d0f61bcb3dcff118d670ae57e728ade521",
"md5": "222a43b03b478a552feb101d91fe8121",
"sha256": "bfb4cd5396928c0affb4f4d4963c1eb7502cd58106b98692e3a3ccd588bd142c"
},
"downloads": -1,
"filename": "necessary-0.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "222a43b03b478a552feb101d91fe8121",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10272,
"upload_time": "2023-06-27T18:17:35",
"upload_time_iso_8601": "2023-06-27T18:17:35.377527Z",
"url": "https://files.pythonhosted.org/packages/d2/fd/7b5a09553f81e7ff5bae6af151d0f61bcb3dcff118d670ae57e728ade521/necessary-0.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ccd501b84f230f7d08d3aebd82937ffefd279b0ca8ab2d03cf3f41e8c6222e25",
"md5": "d6b99e620fa5114dd52e26baf3824328",
"sha256": "381923f9efb13ed613e4a094f154ce3ce36935a39bed58017cc6004be1f74a86"
},
"downloads": -1,
"filename": "necessary-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "d6b99e620fa5114dd52e26baf3824328",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11041,
"upload_time": "2023-06-27T18:17:37",
"upload_time_iso_8601": "2023-06-27T18:17:37.002029Z",
"url": "https://files.pythonhosted.org/packages/cc/d5/01b84f230f7d08d3aebd82937ffefd279b0ca8ab2d03cf3f41e8c6222e25/necessary-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-27 18:17:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "soldni",
"github_project": "necessary",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "necessary"
}
