Skip to content

requires

requires ⚓︎

requires ~ dependency utils

Classes⚓︎

requires.Requirement(_import: str, _from: Optional[str] = None, _as: Optional[str] = None, pip: Optional[Union[str, bool]] = None, conda: Optional[Union[str, bool]] = None, conda_forge: Optional[Union[str, bool]] = None, details: Optional[Union[str, List[str]]] = None) dataclass ⚓︎

Functions⚓︎
requires.Requirement.import_requirement() -> Any ⚓︎

Import and return the requirement

Source code in libs/requires/requires/core.py 
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
def import_requirement(self) -> Any:
    """Import and return the requirement"""
    try:
        if self._from is None:
            return import_module(self._import)
        req = import_module(self._from)
        # Import ok BUT the attr/thing imported from the module does not exist
        try:
            return getattr(req, self._import)
        except AttributeError as ae:
            raise RequirementAttributeError(
                "\n".join(
                    [
                        f"Module/Package(s) import AttributeError: `{self.import_string}`",
                        f"    AttributeError: {str(ae)}",
                    ]
                )
            ) from ae
    except ModuleNotFoundError:
        return RequirementProxy(req=self)

requires.RequirementAttributeError ⚓︎

Bases: AttributeError

Requirement attribute error

requires.RequirementError ⚓︎

Bases: ModuleNotFoundError

Exception for requires

Functions⚓︎

requires.requires(*requirements: Union[str, Dict[str, str], Requirement], _import: Optional[str] = None, _as: Optional[str] = None, _from: Optional[str] = None, pip: Optional[Union[str, bool]] = None, conda: Optional[Union[str, bool]] = None, conda_forge: Optional[Union[str, bool]] = None, details: Optional[str] = None) -> Callable[[Callable[..., T]], Callable[..., T]] ⚓︎

Decorator to specify the packages a function or class requires

The decorator will not do anything unless a NameError is thrown. If a NameError is thrown then the required package is likely not installed and a RequirementError will be thrown with instructions on how to install the required packages.

Parameters:

Name Type Description Default
*requirements Union[str, Dict[str, str], Requirement]

Any number of required package names as strings

 ()
_import 'str'

IMPORT part of from {FROM} import {IMPORT} as {AS}

 None
_as 'str'

AS part of from {FROM} import {IMPORT} as {AS}

 None
_from 'str'

FROM part of from {FROM} import {IMPORT} as {AS}

 None
pip Optional[Union[str, bool]]

pip install name

 None
conda Optional[Union[str, bool]]

conda install name

 None
conda_forge Optional[Union[str, bool]]

conda-forge install name

 None
details str

details to be displayed in the error message

 None

Returns:

Type Description
Callable[[Callable[..., T]], Callable[..., T]]

Function wrapped such that in the event of a NameError a helpful
Callable[[Callable[..., T]], Callable[..., T]]

error is raised.

Raises:

Type Description
ValueError

If requirements or kwargs are given
Source code in libs/requires/requires/core.py 
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
def requires(
    *requirements: Union[str, Dict[str, str], Requirement],
    _import: Optional[str] = None,
    _as: Optional[str] = None,
    _from: Optional[str] = None,
    pip: Optional[Union[str, bool]] = None,
    conda: Optional[Union[str, bool]] = None,
    conda_forge: Optional[Union[str, bool]] = None,
    details: Optional[str] = None,
) -> Callable[[Callable[..., T]], Callable[..., T]]:
    """Decorator to specify the packages a function or class requires

    The decorator will not do anything unless a NameError is thrown. If a
    NameError is thrown then the required package is likely not installed and
    a `RequirementError` will be thrown with instructions on how to install
    the required packages.


    Args:
        *requirements: Any number of required package names as strings
        _import ('str'): `IMPORT` part of `from {FROM} import {IMPORT} as {AS}`
        _as ('str'): `AS` part of `from {FROM} import {IMPORT} as {AS}`
        _from ('str'): `FROM` part of `from {FROM} import {IMPORT} as {AS}`
        pip (Optional[Union[str, bool]]): pip install name
        conda (Optional[Union[str, bool]]): conda install name
        conda_forge (Optional[Union[str, bool]]): conda-forge install name
        details (str): details to be displayed in the error message

    Returns:
        Function wrapped such that in the event of a `NameError` a helpful
        error is raised.

    Raises:
        ValueError: If requirements or kwargs are given

    """
    _kwargs = (_import, _from, _as, pip, conda, conda_forge)
    if any(kw for kw in _kwargs):
        if requirements:
            raise ValueError("*requirements and **kwargs are mutually exclusive")
        _requirements = [
            Requirement(
                _import=str(_import),
                _from=_from,
                _as=_as,
                pip=pip,
                conda=conda,
                conda_forge=conda_forge,
                details=details,
            )
        ]
    else:
        _requirements = make_requirements(list(requirements))

    def _requires_dec(f: Callable[..., T]) -> Callable[..., T]:
        _wrapped_fn = f
        for el in _requirements:
            _wrapped_fn = el(_wrapped_fn)
        wraps(f)(_wrapped_fn)
        return _wrapped_fn

    return _requires_dec

Modules⚓︎

requires.__about__ ⚓︎

Package metadata/info

requires.__main__ ⚓︎

pkg entry ~ python -m requires

Functions⚓︎
requires.__main__.main() -> None ⚓︎

Print package metadata

Source code in libs/requires/requires/__main__.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
def main() -> None:
    """Print package metadata"""
    import json

    sys.stdout.write(
        json.dumps(
            {
                "package": __title__,
                "version": __version__,
                "pkgroot": __pkgroot__,
            },
            indent=2,
        )
    )

requires.core ⚓︎

Core for requires

Classes⚓︎
requires.core.Requirement(_import: str, _from: Optional[str] = None, _as: Optional[str] = None, pip: Optional[Union[str, bool]] = None, conda: Optional[Union[str, bool]] = None, conda_forge: Optional[Union[str, bool]] = None, details: Optional[Union[str, List[str]]] = None) dataclass ⚓︎
Functions⚓︎
requires.core.Requirement.import_requirement() -> Any ⚓︎

Import and return the requirement

Source code in libs/requires/requires/core.py 
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
def import_requirement(self) -> Any:
    """Import and return the requirement"""
    try:
        if self._from is None:
            return import_module(self._import)
        req = import_module(self._from)
        # Import ok BUT the attr/thing imported from the module does not exist
        try:
            return getattr(req, self._import)
        except AttributeError as ae:
            raise RequirementAttributeError(
                "\n".join(
                    [
                        f"Module/Package(s) import AttributeError: `{self.import_string}`",
                        f"    AttributeError: {str(ae)}",
                    ]
                )
            ) from ae
    except ModuleNotFoundError:
        return RequirementProxy(req=self)
requires.core.RequirementAttributeError ⚓︎

Bases: AttributeError

Requirement attribute error

requires.core.RequirementDict ⚓︎

Bases: TypedDict

Requirement dict

requires.core.RequirementError ⚓︎

Bases: ModuleNotFoundError

Exception for requires

Functions⚓︎
requires.core.parse_name_error(ne: NameError) -> List[str] ⚓︎

Return a list of the missing items specified in a NameError

Parameters:

Name Type Description Default
ne NameError

NameError object

 required

Returns:

Name Type Description
str List[str]

name of the missing thing/pkg/module/function

Examples:

>>> args = ("name 'path' is not defined",)
>>> ne = NameError(*args)
>>> parse_name_error(ne)
['path']
Source code in libs/requires/requires/core.py 
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
def parse_name_error(ne: NameError) -> List[str]:
    """Return a list of the missing items specified in a `NameError`

    Args:
        ne (NameError): NameError object

    Returns:
        str: name of the missing thing/pkg/module/function

    Examples:
        >>> args = ("name 'path' is not defined",)
        >>> ne = NameError(*args)
        >>> parse_name_error(ne)
        ['path']

    """
    return [el.split(" ")[1].strip("'") for el in ne.args]
requires.core.requires(*requirements: Union[str, Dict[str, str], Requirement], _import: Optional[str] = None, _as: Optional[str] = None, _from: Optional[str] = None, pip: Optional[Union[str, bool]] = None, conda: Optional[Union[str, bool]] = None, conda_forge: Optional[Union[str, bool]] = None, details: Optional[str] = None) -> Callable[[Callable[..., T]], Callable[..., T]] ⚓︎

Decorator to specify the packages a function or class requires

The decorator will not do anything unless a NameError is thrown. If a NameError is thrown then the required package is likely not installed and a RequirementError will be thrown with instructions on how to install the required packages.

Parameters:

Name Type Description Default
*requirements Union[str, Dict[str, str], Requirement]

Any number of required package names as strings

 ()
_import 'str'

IMPORT part of from {FROM} import {IMPORT} as {AS}

 None
_as 'str'

AS part of from {FROM} import {IMPORT} as {AS}

 None
_from 'str'

FROM part of from {FROM} import {IMPORT} as {AS}

 None
pip Optional[Union[str, bool]]

pip install name

 None
conda Optional[Union[str, bool]]

conda install name

 None
conda_forge Optional[Union[str, bool]]

conda-forge install name

 None
details str

details to be displayed in the error message

 None

Returns:

Type Description
Callable[[Callable[..., T]], Callable[..., T]]

Function wrapped such that in the event of a NameError a helpful
Callable[[Callable[..., T]], Callable[..., T]]

error is raised.

Raises:

Type Description
ValueError

If requirements or kwargs are given
Source code in libs/requires/requires/core.py 
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
def requires(
    *requirements: Union[str, Dict[str, str], Requirement],
    _import: Optional[str] = None,
    _as: Optional[str] = None,
    _from: Optional[str] = None,
    pip: Optional[Union[str, bool]] = None,
    conda: Optional[Union[str, bool]] = None,
    conda_forge: Optional[Union[str, bool]] = None,
    details: Optional[str] = None,
) -> Callable[[Callable[..., T]], Callable[..., T]]:
    """Decorator to specify the packages a function or class requires

    The decorator will not do anything unless a NameError is thrown. If a
    NameError is thrown then the required package is likely not installed and
    a `RequirementError` will be thrown with instructions on how to install
    the required packages.


    Args:
        *requirements: Any number of required package names as strings
        _import ('str'): `IMPORT` part of `from {FROM} import {IMPORT} as {AS}`
        _as ('str'): `AS` part of `from {FROM} import {IMPORT} as {AS}`
        _from ('str'): `FROM` part of `from {FROM} import {IMPORT} as {AS}`
        pip (Optional[Union[str, bool]]): pip install name
        conda (Optional[Union[str, bool]]): conda install name
        conda_forge (Optional[Union[str, bool]]): conda-forge install name
        details (str): details to be displayed in the error message

    Returns:
        Function wrapped such that in the event of a `NameError` a helpful
        error is raised.

    Raises:
        ValueError: If requirements or kwargs are given

    """
    _kwargs = (_import, _from, _as, pip, conda, conda_forge)
    if any(kw for kw in _kwargs):
        if requirements:
            raise ValueError("*requirements and **kwargs are mutually exclusive")
        _requirements = [
            Requirement(
                _import=str(_import),
                _from=_from,
                _as=_as,
                pip=pip,
                conda=conda,
                conda_forge=conda_forge,
                details=details,
            )
        ]
    else:
        _requirements = make_requirements(list(requirements))

    def _requires_dec(f: Callable[..., T]) -> Callable[..., T]:
        _wrapped_fn = f
        for el in _requirements:
            _wrapped_fn = el(_wrapped_fn)
        wraps(f)(_wrapped_fn)
        return _wrapped_fn

    return _requires_dec
requires.core.requires_python(version: str) -> None ⚓︎

Decorator to specify the python version a function or class requires

Source code in libs/requires/requires/core.py 
404
405
406
def requires_python(version: str) -> None:
    """Decorator to specify the python version a function or class requires"""
    raise NotImplementedError("Not yet implemented (TODO)")

requires.shed ⚓︎

Pre-fab requirements

Classes⚓︎