hbutils.testing.requires

Overview:

System requirements conditions for unittest. Can be used on unittest.skipUnless, pytest.mark.skipUnless, etc.

This module provides various condition checkers for testing requirements, including command availability, expression evaluation, and git-related checks. These conditions can be used to conditionally skip tests based on system capabilities and environment setup.

The module aggregates functionality from:

cmd: Command availability checking

expr: Version and environment expression evaluation

git: Git and Git LFS installation and version checking

Example::

>>> from hbutils.testing.requires import vpython, is_git_installed
>>> # Check Python version
>>> vpython >= '3.7'
True
>>> # Check if Git is installed
>>> is_git_installed()
True

vpython

hbutils.testing.requires.vpython = <VersionInfo 3.10.17>

Overview:

Python version expression.

Examples::

>>> import platform
>>> import unittest
>>> from hbutils.testing import vpython
>>> 
>>> class TestMyCase(unittest.TestCase):  # on python 3.6
...     def test_anytime(self):
...         assert 2 + 1 == 3
...
...     @unittest.skipUnless('3.6' <= vpython < '3.7', 'py36 only')  # will run
...     def test_on_python36(self):
...         assert platform.python_version_tuple()[:2] == ('3', '6')
...
...     @unittest.skipUnless('3.7' <= vpython < '3.8', 'py37 only')  # will skip
...     def test_on_python37(self):
...         assert platform.python_version_tuple()[:2] == ('3', '7')
...
>>> unittest.main()
..s
----------------------------------------------------------------------
Ran 3 tests in 0.000s
OK (skipped=1)

vpip

hbutils.testing.requires.vpip = <PipVersionInfo 25.3>

Overview:

Pip version expression

Examples::

>>> import unittest
>>> from hbutils.testing import vpip
>>> 
>>> class TestMyCase(unittest.TestCase):
...     def test_1_anytime(self):
...         assert 2 + 1 == 3
...
...     @unittest.skipUnless(vpip >= '21', 'pip21+ only')  # pip>=21
...     def test_2_on_pip21plus(self):
...         assert True
...
...     @unittest.skipUnless(vpip('pip') >= '21', 'pip21+ only')  # the same as above
...     def test_3_on_pip21plus2(self):
...         assert True
...
...     @unittest.skipUnless(vpip('setuptools') >= '45' or vpip('build') >= '0.8', '')  # setuptools>=45 or build>=0.8
...     def test_4_on_setuptools_or_build(self):
...         assert True
...
...     @unittest.skipUnless(not vpip and vpip('build') >= '0.8', '')  # pip not installed, and build>=0.8
...     def test_5_on_nopip_and_build(self):
...         assert True
... 
>>> unittest.main()
....s
----------------------------------------------------------------------
Ran 5 tests in 0.000s
OK (skipped=1)

OS

class hbutils.testing.requires.OS[source]

Overview:

Expressions for operating system.

Examples::

>>> import unittest
>>> from hbutils.testing import OS
>>>
>>> class TestMyCase(unittest.TestCase):  # on Linux
...     def test_1_anytime(self):
...         assert 2 + 1 == 3
...
...     @unittest.skipUnless(OS.linux, 'linux only')  # only run on Linux
...     def test_2_linux(self):
...         assert True
...
...     @unittest.skipUnless(OS.windows, 'windows only')  # only run on Windows
...     def test_2_windows(self):
...         assert True
...
...     @unittest.skipUnless(OS.macos, 'macos only')  # only run on macOS
...     def test_4_macos(self):
...         assert True
...
>>> unittest.main()
..ss
----------------------------------------------------------------------
Ran 4 tests in 0.001s
OK (skipped=2)

darwin = False: Is darwin (macos) system or not, related to your local OS.

linux = True: Is linux system or not, related to your local OS.

macos = False: Alias for OS.darwin.

windows = False: Is windows system or not, related to your local OS.

Impl

class hbutils.testing.requires.Impl[source]

Overview:

Expression for python implementation. See platform.python_implementation() .

Examples::

>>> import unittest
>>> from hbutils.testing import Impl
>>>
>>> class TestMyCase(unittest.TestCase):  # on CPython
...     def test_1_anytime(self):
...         assert 2 + 1 == 3
...
...     @unittest.skipUnless(Impl.cpython, 'cpython only')  # only run on CPython
...     def test_2_cpython(self):
...         assert True
...
...     @unittest.skipUnless(Impl.pypy, 'pypy only')  # only run on PyPy
...     def test_3_pypy(self):
...         assert True
...
...     @unittest.skipUnless(Impl.iron_python, 'ironpython only')  # only run on IronPython
...     def test_4_ironpython(self):
...         assert True
...
...     @unittest.skipUnless(Impl.jython, 'jython only')  # only run on Jython
...     def test_5_jython(self):
...         assert True
...
>>> unittest.main()
..sss
----------------------------------------------------------------------
Ran 5 tests in 0.000s
OK (skipped=3)

cpython = True: Is CPython (most-frequently-used python) or not, related to your local python.

iron_python = False: Is IronPython or not, related to your local python.

jython = False: Is Jython (java-based python) or not, related to your local python.

pypy = False: Is PyPy or not, related to your local python.

cmdv

hbutils.testing.requires.cmdv(execfile: str) → bool[source]

Check if the given command exists in this environment.

This function behaves like the command -v xxx command in Linux, checking whether an executable file is available in the system PATH. It is useful for verifying dependencies or determining platform-specific command availability.

Parameters:: execfile (str) – Executable file name to check, such as python, bash, or apt-get.
Returns:: True if the executable file exists in the system PATH, False otherwise.
Return type:: bool

Examples::

>>> from hbutils.testing import cmdv
>>>
>>> cmdv('apt-get')  # should exist on Ubuntu
True
>>> cmdv('bash')  # should exist on Linux
True
>>> cmdv('cmd')  # should exist on Windows
False
>>> cmdv('not_installed')
False

is_git_installed

hbutils.testing.requires.is_git_installed(git_path: str | None = None) → bool[source]

Check if Git is installed.

Parameters:: git_path (Optional[str]) – Optional path to the Git executable. If not provided, the function will attempt to find Git in the system PATH.
Returns:: True if Git is installed, False otherwise.
Return type:: bool

Example::

>>> is_git_installed()
True
>>> is_git_installed('/custom/path/to/git')
True

git_version

hbutils.testing.requires.git_version(git_path: str | None = None) → VersionInfo | None[source]

Get the Git version.

Parameters:: git_path (Optional[str]) – Optional path to the Git executable. If not provided, the function will attempt to find Git in the system PATH.
Returns:: A VersionInfo object representing the Git version, or None if Git is not installed or the version cannot be determined.
Return type:: Optional[VersionInfo]

Note

This function may return None even if Git is installed, in cases where the ‘git –version’ output is unrecognizable.

Example::

>>> version = git_version()
>>> if version:
...     print(f"Git version: {version}")
... else:
...     print("Git version could not be determined")
Git version: 2.34.1

is_git_lfs_installed

hbutils.testing.requires.is_git_lfs_installed(git_path: str | None = None) → bool[source]

Check if Git LFS is installed.

Parameters:: git_path (Optional[str]) – Optional path to the Git executable. If not provided, the function will attempt to find Git in the system PATH.
Returns:: True if both Git and Git LFS are installed, False otherwise.
Return type:: bool

Example::

>>> is_git_lfs_installed()
True
>>> is_git_lfs_installed('/custom/path/to/git')
False

git_lfs_version

hbutils.testing.requires.git_lfs_version(git_path: str | None = None) → VersionInfo | None[source]

Get the Git LFS version.

Parameters:: git_path (Optional[str]) – Optional path to the Git executable. If not provided, the function will attempt to find Git in the system PATH.
Returns:: A VersionInfo object representing the Git LFS version, or None if Git LFS is not installed or the version cannot be determined.
Return type:: Optional[VersionInfo]

Note

This function may return None even if Git LFS is installed, in cases where the ‘git lfs version’ output is unrecognizable.

Example::

>>> version = git_lfs_version()
>>> if version:
...     print(f"Git LFS version: {version}")
... else:
...     print("Git LFS version could not be determined")
Git LFS version: 3.2.0