hbutils.system.python.package

Utilities for managing Python package requirements and invoking pip commands.

This module offers a lightweight API for interacting with Python packaging metadata, parsing requirements files, evaluating environment markers, and running pip commands programmatically. It is designed to simplify dependency management tasks within Python applications and scripts.

The module contains the following main components:

package_version() - Retrieve the installed version of a package
load_req_file() - Parse a requirements file into requirement strings
pip() - Invoke the pip command with arbitrary arguments
check_reqs() - Verify whether a list of requirements is satisfied
check_req_file() - Verify requirements from a file
pip_install() - Install requirements programmatically
pip_install_req_file() - Install requirements from a file

Note

Requirement marker evaluation follows PEP 508. Requirements with markers that do not evaluate to true in the current environment are ignored.

Example:

>>> from hbutils.system.python.package import (
...     package_version, load_req_file, check_reqs, pip_install
... )
>>> package_version('pip')
<Version('...')>
>>> reqs = load_req_file('requirements.txt')
>>> if not check_reqs(reqs):
...     pip_install(reqs)

all

hbutils.system.python.package.__all__ = ['package_version', 'load_req_file', 'pip', 'check_reqs', 'check_req_file', 'pip_install', 'pip_install_req_file']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

package_version

hbutils.system.python.package.package_version(name: str) → Version | None[source]

Get version of package with given name.

Parameters:: name (str) – Name of the package, case is not sensitive.
Returns:: A packaging.version.Version object. If the package is not installed, return None.
Return type:: Optional[Version]

Examples::

>>> from hbutils.system import package_version
>>>
>>> package_version('pip')
<Version('21.3.1')>
>>> package_version('setuptools')
<Version('59.6.0')>
>>> package_version('not_a_package')
None

yield_lines

hbutils.system.python.package.yield_lines(iterable: Iterable[str]) → Iterator[str][source]

hbutils.system.python.package.yield_lines(text: str) → Iterator[str]

Yield valid lines of a string or iterable.

Based on https://github.com/jaraco/jaraco.text/blob/main/jaraco/text/__init__.py#L537 .

Parameters:: iterable (Iterable[str]) – An iterable of strings or a string.
Returns:: Generator yielding valid non-blank lines.
Return type:: Iterator[str]

Examples::

>>> list(yield_lines(''))
[]
>>> list(yield_lines(['foo', 'bar']))
['foo', 'bar']
>>> list(yield_lines('foo\nbar'))
['foo', 'bar']
>>> list(yield_lines('\nfoo\n#bar\nbaz #comment'))
['foo', 'baz #comment']
>>> list(yield_lines(['foo\nbar', 'baz', 'bing\n\n\n']))
['foo', 'bar', 'baz', 'bing']

drop_comment

hbutils.system.python.package.drop_comment(line: str) → str[source]

Drop comments from a line.

Based on https://github.com/jaraco/jaraco.text/blob/main/jaraco/text/__init__.py#L560 .

Parameters:: line (str) – Line of text to process.
Returns:: Line with comment removed.
Return type:: str

Examples::

>>> drop_comment('foo # bar')
'foo'

A hash without a space may be in a URL::

>>> drop_comment('https://example.com/foo#bar')
'https://example.com/foo#bar'

join_continuation

hbutils.system.python.package.join_continuation(lines: Iterable[str]) → Iterator[str][source]

Join lines continued by a trailing backslash.

Based on https://github.com/jaraco/jaraco.text/blob/main/jaraco/text/__init__.py#L575 .

Parameters:: lines (Iterable[str]) – Iterable of lines to process.
Returns:: Generator yielding joined lines.
Return type:: Iterator[str]

Examples::

>>> list(join_continuation(['foo \\', 'bar', 'baz']))
['foobar', 'baz']
>>> list(join_continuation(['foo \\', 'bar', 'baz']))
['foobar', 'baz']
>>> list(join_continuation(['foo \\', 'bar \\', 'baz']))
['foobarbaz']

Note:

The character preceding the backslash is also elided::

>>> list(join_continuation(['goo\\', 'dly']))
['godly']

If no line is available to continue, suppress the lines::

>>> list(join_continuation(['foo', 'bar\\', 'baz\\']))
['foo']

load_req_file

hbutils.system.python.package.load_req_file(requirements_file: str) → List[str][source]

Load requirements items from a requirements.txt file.

Parameters:: requirements_file (str) – Requirements file path.
Returns:: List of requirements.
Return type:: List[str]

Examples::

>>> from hbutils.system import load_req_file
>>> load_req_file('requirements.txt')
['packaging>=21.3', 'setuptools>=50.0']

pip

hbutils.system.python.package.pip(*args: str, silent: bool = False) → None[source]

Run pip command with code.

Parameters:

args (str) – Command line arguments for pip command.
silent (bool) – Do not print anything. Default is False, which means print the output to sys.stdout and sys.stderr.

Raises:

AssertionError – If pip command returns non-zero exit code.

Examples::

>>> from hbutils.system import pip
>>> pip('-V')
pip 22.3.1 from /home/user/myproject/venv/lib/python3.7/site-packages/pip (python 3.7)
>>> pip('-V', silent=True)  # nothing will be printed

check_reqs

hbutils.system.python.package.check_reqs(reqs: List[str]) → bool[source]

Check if the given requirements are all satisfied.

Parameters:: reqs (List[str]) – List of requirements.
Returns:: All the requirements in reqs satisfied or not.
Return type:: bool

Examples::

>>> from hbutils.system import check_reqs
>>> check_reqs(['pip>=20.0'])
True
>>> check_reqs(['pip~=19.2'])
False
>>> check_reqs(['pip>=20.0', 'setuptools>=50.0'])
True

Note

If a requirement’s marker is not satisfied in this environment, it will be ignored instead of return False.

check_req_file

hbutils.system.python.package.check_req_file(requirements_file: str) → bool[source]

Check if the requirements in the given requirements_file is satisfied.

Parameters:: requirements_file (str) – Requirements file, such as requirements.txt.
Returns:: All the requirements in requirements_file satisfied or not.
Return type:: bool

Examples::

>>> from hbutils.system import check_req_file
>>>
>>> check_req_file('requirements.txt')
True
>>> check_req_file('requirements-test.txt')
True

pip_install

hbutils.system.python.package.pip_install(reqs: List[str], silent: bool = False, force: bool = False, user: bool = False) → None[source]

Pip install requirements with code.

Similar to pip install req1 req2 ....

Parameters:

reqs (List[str]) – Requirement items to install.
silent (bool) – Do not print anything. Default is False.
force (bool) – Force execute the pip install command. Default is False which means the requirements will be checked before installation, and the installation will be only executed when some requirements not installed.
user (bool) – User mode, represents --user option in pip.

Examples::

>>> from hbutils.system import pip_install
>>> pip_install(['scikit-learn'])  # not installed
Looking in indexes: https://xxx/simple
Collecting scikit-learn
  Using cached https://xxx/scikit_learn-1.0.2-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (24.8 MB)
Installing collected packages: threadpoolctl, scipy, joblib, scikit-learn
Successfully installed joblib-1.2.0 scikit-learn-1.0.2 scipy-1.7.3 threadpoolctl-3.1.0
>>> pip_install(['numpy>=1.10.0'])  # installed
>>> pip_install(['numpy>=1.10.0'], force=True)  # force execute
Looking in indexes: https://xxx/simple
Requirement already satisfied: numpy>=1.10.0 in ./venv/lib/python3.7/site-packages (1.21.6)

pip_install_req_file

hbutils.system.python.package.pip_install_req_file(requirements_file: str, silent: bool = False, force: bool = False, user: bool = False) → None[source]

Pip install requirements from file with code.

Similar to pip install -r requirements.txt.

Parameters:

requirements_file (str) – Requirements file, such as requirements.txt.
silent (bool) – Do not print anything. Default is False.
force (bool) – Force execute the pip install command. Default is False which means the requirements will be checked before installation, and the installation will be only executed when some requirements not installed.
user (bool) – User mode, represents --user option in pip.

Examples::

>>> from hbutils.system import pip_install_req_file
>>> pip_install_req_file('requirements.txt')  # pip install -r requirements.txt

hbutils.system.python.package

__all__

package_version

yield_lines

drop_comment

join_continuation

load_req_file

pip

check_reqs

check_req_file

pip_install

pip_install_req_file

all