| Name | test-imports JSON |
| Version |
1.0.2
JSON |
| download |
| home_page | None |
| Summary | A Python package for failing and mocking imports in automated tests |
| upload_time | 2023-10-12 14:02:40 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | None |
| keywords |
import
mock
test
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Test Python imports
A Python package for failing and mocking imports in automated tests.
**Note:** This package was made with CPython in mind. There are no guarantees that it will work with other versions.
## Content
1. [Failing imports](#failing-imports)
2. [Mocking imports](#mocking-imports)
## Failing imports
This was the original motive to create the package. I needed to test the behaviour of another package that had optional support for [`PIL`](https://python-pillow.org), and I wanted the tests to check the behaviour both when the package is present and when it is not.
The usage is straightforward:
```python
from test_imports import fail_imports
def f() -> bool:
try:
import PIL.Image
except ImportError:
return False
else:
return True
def test_success() -> None:
assert f() is True
@fail_imports("PIL")
def test_decorator_fail() -> None:
assert f() is False
def test_context_manager_fail() -> None:
with fail_imports("PIL"):
assert f() is False
test_success()
test_decorator_fail()
test_context_manager_fail()
```
All positional arguments in `fail_imports` are treated as the modules whose imports are to fail. Each of them can be:
* a compiled regular expression, matched (using `re.match`, i.e., anchored at the beginning of the string) against names of the modules being imported; or
* a string, which is matched literally, except for the asterisk, which is used to match any substring. The matching is done on complete strings.
For example, `"foo.bar*"` will match `foo.bar` and `foo.bard`, but not `foodbar` (because dot is matched literally, not as in regular expressions). Further, `"foo.*r"` will match `foo.bar`, but not `foo.bard` because only the whole strings are matched. If you want `foo.bard` to match, the expression needs to be `foo.*r*`, or you can supply a compiled regular expression that would match it.
This function also supports some customisation through keyword-only arguments:
* `hide_modules` is a sequence of module names matching patterns (as described above) that won't be failed, but will be removed from `sys.modules`, thus causing them to "reload". This helps test imports inside those modules because, if they are not "reloaded", their imports are not re-executed.
* `exception` is either a class or an instance of the exception to be raised when an import fails. Unsurprisingly, this defaults to `ModuleNotFoundError`.
* `debug` is a Boolean flag. If set to `True`, the package will produce extra prints in an attempt to help with its usage.
## Mocking imports
Like more "normal" mocking, the mocking of modules is used to replace one object with another one, pretending to be the original. On the surface, mocking imports is easy:
```python
from test_imports import mock_imports
def test_success() -> None:
import math
assert hasattr(math, "sin")
assert not hasattr(math, "digits")
@mock_imports(math="string")
def test_decorator_fail() -> None:
import math
assert not hasattr(math, "sin")
assert hasattr(math, "digits")
def test_context_manager_fail() -> None:
with mock_imports(math="string"):
import math
assert not hasattr(math, "sin")
assert hasattr(math, "digits")
test_success()
test_decorator_fail()
test_context_manager_fail()
```
However, mocking definitions are a bit more complicated than the ones for `fail_imports`.
First, there is a problem of mocking modules inside packages. One cannot do `fail_imports(PIL.Image="mock_pil_image")` because dots cannot be a part of arguments' names. Instead, we use double underscores (similar to, for example, Django):
```python
with mock_imports(PIL__Image="math"):
from PIL import Image
assert not hasattr(Image, "new")
assert hasattr(Image, "sin")
```
There is also a potential problem of collisions in names between the function's arguments and mocked modules. For example, there is a package [debug](https://pypi.org/project/debug/), which we could not mock if `debug` was used as a keyword argument to turn on debugging outputs. That's why argument names are prefixed with `"TI_"` (so, `TI_debug=True` instead of `debug=True`).
Both of these can still cause potential conflicts. Some module can have double underscores in its name and some package's name could start with `TI_`. To account for these cases, `mock_imports` takes two positional-only arguments:
* `prefix` is the prefix for keyword-only arguments that are recognised by this function. For example, if `prefix` is set to its default version `"TI_"`, then the debugging value is assigned as `TI_debug`. Any names beginning with `"TI_"` that are not recognised as arguments are considered invalid.
In other words, if you want to mock a module with a name starting with `"TI_"` (for example, `TI_module`), you need to change this prefix to something else and adjust keyword-arguments accordingly.
* `dot` is the string used instead of dot in module names.
So, these two calls are equivalent:
```python
mock_imports(PIL__Image="mock_pil_image", TI_debug=True)
# and
mock_imports(
"PREFIX_", "__xxx__", PIL__xxx__Image="mock_pil_image", PREFIX_debug=True,
)
```
This still does not allow matching with asterisk or with regular expressions, but it would hardly make sense to do so (mocking multiple different modules with the same one). However, if really needed, one can use the following Python "trick":
```python
mock_imports(**{"tests.module*": math})
```
This will will load `math` instead of any module with a full name beginning with `"tests.module"`.
The remaining arguments are keyword only (always prefix their names with `prefix`!):
* `hide_modules` is as above: a sequence of module names matching patterns (as described above) that won't be failed, but will be removed from `sys.modules`, thus causing them to "reload". This helps test imports inside those modules because, if they are not "reloaded", their imports are not re-executed.
* `reload` is a Boolean flag. If `True`, every imported module or its mock is reloaded on import. Depending on how they are written, this may help reset mocked modules from previous tests.
* `debug` is a Boolean flag. If set to `True`, the package will produce extra prints in an attempt to help with its usage.
Raw data
{
"_id": null,
"home_page": null,
"name": "test-imports",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "import,mock,test",
"author": null,
"author_email": "Vedran Sego <vsego@vsego.org>",
"download_url": "https://files.pythonhosted.org/packages/9d/1a/8bc14d4aa638dca1b3257a86cc43756e617ccd4fd567f16affc72faab0aa/test_imports-1.0.2.tar.gz",
"platform": null,
"description": "# Test Python imports\n\nA Python package for failing and mocking imports in automated tests.\n\n**Note:** This package was made with CPython in mind. There are no guarantees that it will work with other versions.\n\n## Content\n\n1. [Failing imports](#failing-imports)\n2. [Mocking imports](#mocking-imports)\n\n## Failing imports\n\nThis was the original motive to create the package. I needed to test the behaviour of another package that had optional support for [`PIL`](https://python-pillow.org), and I wanted the tests to check the behaviour both when the package is present and when it is not.\n\nThe usage is straightforward:\n\n```python\nfrom test_imports import fail_imports\n\n\ndef f() -> bool:\n try:\n import PIL.Image\n except ImportError:\n return False\n else:\n return True\n\n\ndef test_success() -> None:\n assert f() is True\n\n\n@fail_imports(\"PIL\")\ndef test_decorator_fail() -> None:\n assert f() is False\n\n\ndef test_context_manager_fail() -> None:\n with fail_imports(\"PIL\"):\n assert f() is False\n\n\ntest_success()\ntest_decorator_fail()\ntest_context_manager_fail()\n```\n\nAll positional arguments in `fail_imports` are treated as the modules whose imports are to fail. Each of them can be:\n\n* a compiled regular expression, matched (using `re.match`, i.e., anchored at the beginning of the string) against names of the modules being imported; or\n\n* a string, which is matched literally, except for the asterisk, which is used to match any substring. The matching is done on complete strings. \n For example, `\"foo.bar*\"` will match `foo.bar` and `foo.bard`, but not `foodbar` (because dot is matched literally, not as in regular expressions). Further, `\"foo.*r\"` will match `foo.bar`, but not `foo.bard` because only the whole strings are matched. If you want `foo.bard` to match, the expression needs to be `foo.*r*`, or you can supply a compiled regular expression that would match it.\n\nThis function also supports some customisation through keyword-only arguments:\n\n* `hide_modules` is a sequence of module names matching patterns (as described above) that won't be failed, but will be removed from `sys.modules`, thus causing them to \"reload\". This helps test imports inside those modules because, if they are not \"reloaded\", their imports are not re-executed.\n\n* `exception` is either a class or an instance of the exception to be raised when an import fails. Unsurprisingly, this defaults to `ModuleNotFoundError`.\n\n* `debug` is a Boolean flag. If set to `True`, the package will produce extra prints in an attempt to help with its usage.\n\n## Mocking imports\n\nLike more \"normal\" mocking, the mocking of modules is used to replace one object with another one, pretending to be the original. On the surface, mocking imports is easy:\n\n```python\nfrom test_imports import mock_imports\n\n\ndef test_success() -> None:\n import math\n assert hasattr(math, \"sin\")\n assert not hasattr(math, \"digits\")\n\n\n@mock_imports(math=\"string\")\ndef test_decorator_fail() -> None:\n import math\n assert not hasattr(math, \"sin\")\n assert hasattr(math, \"digits\")\n\n\ndef test_context_manager_fail() -> None:\n with mock_imports(math=\"string\"):\n import math\n assert not hasattr(math, \"sin\")\n assert hasattr(math, \"digits\")\n\n\ntest_success()\ntest_decorator_fail()\ntest_context_manager_fail()\n```\n\nHowever, mocking definitions are a bit more complicated than the ones for `fail_imports`.\n\nFirst, there is a problem of mocking modules inside packages. One cannot do `fail_imports(PIL.Image=\"mock_pil_image\")` because dots cannot be a part of arguments' names. Instead, we use double underscores (similar to, for example, Django):\n\n```python\nwith mock_imports(PIL__Image=\"math\"):\n from PIL import Image\n assert not hasattr(Image, \"new\")\n assert hasattr(Image, \"sin\")\n```\n\nThere is also a potential problem of collisions in names between the function's arguments and mocked modules. For example, there is a package [debug](https://pypi.org/project/debug/), which we could not mock if `debug` was used as a keyword argument to turn on debugging outputs. That's why argument names are prefixed with `\"TI_\"` (so, `TI_debug=True` instead of `debug=True`).\n\nBoth of these can still cause potential conflicts. Some module can have double underscores in its name and some package's name could start with `TI_`. To account for these cases, `mock_imports` takes two positional-only arguments:\n\n* `prefix` is the prefix for keyword-only arguments that are recognised by this function. For example, if `prefix` is set to its default version `\"TI_\"`, then the debugging value is assigned as `TI_debug`. Any names beginning with `\"TI_\"` that are not recognised as arguments are considered invalid. \n In other words, if you want to mock a module with a name starting with `\"TI_\"` (for example, `TI_module`), you need to change this prefix to something else and adjust keyword-arguments accordingly.\n\n* `dot` is the string used instead of dot in module names.\n\n So, these two calls are equivalent:\n\n```python\nmock_imports(PIL__Image=\"mock_pil_image\", TI_debug=True)\n# and\nmock_imports(\n \"PREFIX_\", \"__xxx__\", PIL__xxx__Image=\"mock_pil_image\", PREFIX_debug=True,\n)\n```\n\nThis still does not allow matching with asterisk or with regular expressions, but it would hardly make sense to do so (mocking multiple different modules with the same one). However, if really needed, one can use the following Python \"trick\":\n\n```python\nmock_imports(**{\"tests.module*\": math})\n```\n\nThis will will load `math` instead of any module with a full name beginning with `\"tests.module\"`.\n\nThe remaining arguments are keyword only (always prefix their names with `prefix`!):\n\n* `hide_modules` is as above: a sequence of module names matching patterns (as described above) that won't be failed, but will be removed from `sys.modules`, thus causing them to \"reload\". This helps test imports inside those modules because, if they are not \"reloaded\", their imports are not re-executed.\n\n* `reload` is a Boolean flag. If `True`, every imported module or its mock is reloaded on import. Depending on how they are written, this may help reset mocked modules from previous tests.\n\n* `debug` is a Boolean flag. If set to `True`, the package will produce extra prints in an attempt to help with its usage.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python package for failing and mocking imports in automated tests",
"version": "1.0.2",
"project_urls": {
"Bug Tracker": "https://github.com/vsego/test-imports/issues",
"Changelog": "https://github.com/vsego/test-imports/blob/master/CHANGELOG.md",
"Homepage": "https://github.com/vsego/test-imports"
},
"split_keywords": [
"import",
"mock",
"test"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d39f26c59d877210ae3c12932c429dc58e118d97db639f78fb454af7342171e9",
"md5": "c1a9d9d136c4e123c9d1f0188ad215cb",
"sha256": "cee042385fe451ad17ef06a1824991afaf03571e3bb79f497c31c9b3d1d712ac"
},
"downloads": -1,
"filename": "test_imports-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c1a9d9d136c4e123c9d1f0188ad215cb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 13311,
"upload_time": "2023-10-12T14:02:42",
"upload_time_iso_8601": "2023-10-12T14:02:42.258110Z",
"url": "https://files.pythonhosted.org/packages/d3/9f/26c59d877210ae3c12932c429dc58e118d97db639f78fb454af7342171e9/test_imports-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9d1a8bc14d4aa638dca1b3257a86cc43756e617ccd4fd567f16affc72faab0aa",
"md5": "3dc11e7f5eebd9828aef2349521c916b",
"sha256": "e41a45786716455007fd468c75b0308707050f585d46d4c8f1bf369a343a0ecd"
},
"downloads": -1,
"filename": "test_imports-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "3dc11e7f5eebd9828aef2349521c916b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 17063,
"upload_time": "2023-10-12T14:02:40",
"upload_time_iso_8601": "2023-10-12T14:02:40.541805Z",
"url": "https://files.pythonhosted.org/packages/9d/1a/8bc14d4aa638dca1b3257a86cc43756e617ccd4fd567f16affc72faab0aa/test_imports-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-12 14:02:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vsego",
"github_project": "test-imports",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "test-imports"
}
