monkeypatch.py 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435
  1. # mypy: allow-untyped-defs
  2. """Monkeypatching and mocking functionality."""
  3. from __future__ import annotations
  4. from collections.abc import Generator
  5. from collections.abc import Mapping
  6. from collections.abc import MutableMapping
  7. from contextlib import contextmanager
  8. import os
  9. from pathlib import Path
  10. import re
  11. import sys
  12. from typing import Any
  13. from typing import final
  14. from typing import overload
  15. from typing import TypeVar
  16. import warnings
  17. from _pytest.deprecated import MONKEYPATCH_LEGACY_NAMESPACE_PACKAGES
  18. from _pytest.fixtures import fixture
  19. from _pytest.warning_types import PytestWarning
  20. RE_IMPORT_ERROR_NAME = re.compile(r"^No module named (.*)$")
  21. K = TypeVar("K")
  22. V = TypeVar("V")
  23. @fixture
  24. def monkeypatch() -> Generator[MonkeyPatch]:
  25. """A convenient fixture for monkey-patching.
  26. The fixture provides these methods to modify objects, dictionaries, or
  27. :data:`os.environ`:
  28. * :meth:`monkeypatch.setattr(obj, name, value, raising=True) <pytest.MonkeyPatch.setattr>`
  29. * :meth:`monkeypatch.delattr(obj, name, raising=True) <pytest.MonkeyPatch.delattr>`
  30. * :meth:`monkeypatch.setitem(mapping, name, value) <pytest.MonkeyPatch.setitem>`
  31. * :meth:`monkeypatch.delitem(obj, name, raising=True) <pytest.MonkeyPatch.delitem>`
  32. * :meth:`monkeypatch.setenv(name, value, prepend=None) <pytest.MonkeyPatch.setenv>`
  33. * :meth:`monkeypatch.delenv(name, raising=True) <pytest.MonkeyPatch.delenv>`
  34. * :meth:`monkeypatch.syspath_prepend(path) <pytest.MonkeyPatch.syspath_prepend>`
  35. * :meth:`monkeypatch.chdir(path) <pytest.MonkeyPatch.chdir>`
  36. * :meth:`monkeypatch.context() <pytest.MonkeyPatch.context>`
  37. All modifications will be undone after the requesting test function or
  38. fixture has finished. The ``raising`` parameter determines if a :class:`KeyError`
  39. or :class:`AttributeError` will be raised if the set/deletion operation does not have the
  40. specified target.
  41. To undo modifications done by the fixture in a contained scope,
  42. use :meth:`context() <pytest.MonkeyPatch.context>`.
  43. """
  44. mpatch = MonkeyPatch()
  45. yield mpatch
  46. mpatch.undo()
  47. def resolve(name: str) -> object:
  48. # Simplified from zope.dottedname.
  49. parts = name.split(".")
  50. used = parts.pop(0)
  51. found: object = __import__(used)
  52. for part in parts:
  53. used += "." + part
  54. try:
  55. found = getattr(found, part)
  56. except AttributeError:
  57. pass
  58. else:
  59. continue
  60. # We use explicit un-nesting of the handling block in order
  61. # to avoid nested exceptions.
  62. try:
  63. __import__(used)
  64. except ImportError as ex:
  65. expected = str(ex).split()[-1]
  66. if expected == used:
  67. raise
  68. else:
  69. raise ImportError(f"import error in {used}: {ex}") from ex
  70. found = annotated_getattr(found, part, used)
  71. return found
  72. def annotated_getattr(obj: object, name: str, ann: str) -> object:
  73. try:
  74. obj = getattr(obj, name)
  75. except AttributeError as e:
  76. raise AttributeError(
  77. f"{type(obj).__name__!r} object at {ann} has no attribute {name!r}"
  78. ) from e
  79. return obj
  80. def derive_importpath(import_path: str, raising: bool) -> tuple[str, object]:
  81. if not isinstance(import_path, str) or "." not in import_path:
  82. raise TypeError(f"must be absolute import path string, not {import_path!r}")
  83. module, attr = import_path.rsplit(".", 1)
  84. target = resolve(module)
  85. if raising:
  86. annotated_getattr(target, attr, ann=module)
  87. return attr, target
  88. class Notset:
  89. def __repr__(self) -> str:
  90. return "<notset>"
  91. notset = Notset()
  92. @final
  93. class MonkeyPatch:
  94. """Helper to conveniently monkeypatch attributes/items/environment
  95. variables/syspath.
  96. Returned by the :fixture:`monkeypatch` fixture.
  97. .. versionchanged:: 6.2
  98. Can now also be used directly as `pytest.MonkeyPatch()`, for when
  99. the fixture is not available. In this case, use
  100. :meth:`with MonkeyPatch.context() as mp: <context>` or remember to call
  101. :meth:`undo` explicitly.
  102. """
  103. def __init__(self) -> None:
  104. self._setattr: list[tuple[object, str, object]] = []
  105. self._setitem: list[tuple[Mapping[Any, Any], object, object]] = []
  106. self._cwd: str | None = None
  107. self._savesyspath: list[str] | None = None
  108. @classmethod
  109. @contextmanager
  110. def context(cls) -> Generator[MonkeyPatch]:
  111. """Context manager that returns a new :class:`MonkeyPatch` object
  112. which undoes any patching done inside the ``with`` block upon exit.
  113. Example:
  114. .. code-block:: python
  115. import functools
  116. def test_partial(monkeypatch):
  117. with monkeypatch.context() as m:
  118. m.setattr(functools, "partial", 3)
  119. Useful in situations where it is desired to undo some patches before the test ends,
  120. such as mocking ``stdlib`` functions that might break pytest itself if mocked (for examples
  121. of this see :issue:`3290`).
  122. """
  123. m = cls()
  124. try:
  125. yield m
  126. finally:
  127. m.undo()
  128. @overload
  129. def setattr(
  130. self,
  131. target: str,
  132. name: object,
  133. value: Notset = ...,
  134. raising: bool = ...,
  135. ) -> None: ...
  136. @overload
  137. def setattr(
  138. self,
  139. target: object,
  140. name: str,
  141. value: object,
  142. raising: bool = ...,
  143. ) -> None: ...
  144. def setattr(
  145. self,
  146. target: str | object,
  147. name: object | str,
  148. value: object = notset,
  149. raising: bool = True,
  150. ) -> None:
  151. """
  152. Set attribute value on target, memorizing the old value.
  153. For example:
  154. .. code-block:: python
  155. import os
  156. monkeypatch.setattr(os, "getcwd", lambda: "/")
  157. The code above replaces the :func:`os.getcwd` function by a ``lambda`` which
  158. always returns ``"/"``.
  159. For convenience, you can specify a string as ``target`` which
  160. will be interpreted as a dotted import path, with the last part
  161. being the attribute name:
  162. .. code-block:: python
  163. monkeypatch.setattr("os.getcwd", lambda: "/")
  164. Raises :class:`AttributeError` if the attribute does not exist, unless
  165. ``raising`` is set to False.
  166. **Where to patch**
  167. ``monkeypatch.setattr`` works by (temporarily) changing the object that a name points to with another one.
  168. There can be many names pointing to any individual object, so for patching to work you must ensure
  169. that you patch the name used by the system under test.
  170. See the section :ref:`Where to patch <python:where-to-patch>` in the :mod:`unittest.mock`
  171. docs for a complete explanation, which is meant for :func:`unittest.mock.patch` but
  172. applies to ``monkeypatch.setattr`` as well.
  173. """
  174. __tracebackhide__ = True
  175. import inspect
  176. if isinstance(value, Notset):
  177. if not isinstance(target, str):
  178. raise TypeError(
  179. "use setattr(target, name, value) or "
  180. "setattr(target, value) with target being a dotted "
  181. "import string"
  182. )
  183. value = name
  184. name, target = derive_importpath(target, raising)
  185. else:
  186. if not isinstance(name, str):
  187. raise TypeError(
  188. "use setattr(target, name, value) with name being a string or "
  189. "setattr(target, value) with target being a dotted "
  190. "import string"
  191. )
  192. oldval = getattr(target, name, notset)
  193. if raising and oldval is notset:
  194. raise AttributeError(f"{target!r} has no attribute {name!r}")
  195. # avoid class descriptors like staticmethod/classmethod
  196. if inspect.isclass(target):
  197. oldval = target.__dict__.get(name, notset)
  198. self._setattr.append((target, name, oldval))
  199. setattr(target, name, value)
  200. def delattr(
  201. self,
  202. target: object | str,
  203. name: str | Notset = notset,
  204. raising: bool = True,
  205. ) -> None:
  206. """Delete attribute ``name`` from ``target``.
  207. If no ``name`` is specified and ``target`` is a string
  208. it will be interpreted as a dotted import path with the
  209. last part being the attribute name.
  210. Raises AttributeError it the attribute does not exist, unless
  211. ``raising`` is set to False.
  212. """
  213. __tracebackhide__ = True
  214. import inspect
  215. if isinstance(name, Notset):
  216. if not isinstance(target, str):
  217. raise TypeError(
  218. "use delattr(target, name) or "
  219. "delattr(target) with target being a dotted "
  220. "import string"
  221. )
  222. name, target = derive_importpath(target, raising)
  223. if not hasattr(target, name):
  224. if raising:
  225. raise AttributeError(name)
  226. else:
  227. oldval = getattr(target, name, notset)
  228. # Avoid class descriptors like staticmethod/classmethod.
  229. if inspect.isclass(target):
  230. oldval = target.__dict__.get(name, notset)
  231. self._setattr.append((target, name, oldval))
  232. delattr(target, name)
  233. def setitem(self, dic: Mapping[K, V], name: K, value: V) -> None:
  234. """Set dictionary entry ``name`` to value."""
  235. self._setitem.append((dic, name, dic.get(name, notset)))
  236. # Not all Mapping types support indexing, but MutableMapping doesn't support TypedDict
  237. dic[name] = value # type: ignore[index]
  238. def delitem(self, dic: Mapping[K, V], name: K, raising: bool = True) -> None:
  239. """Delete ``name`` from dict.
  240. Raises ``KeyError`` if it doesn't exist, unless ``raising`` is set to
  241. False.
  242. """
  243. if name not in dic:
  244. if raising:
  245. raise KeyError(name)
  246. else:
  247. self._setitem.append((dic, name, dic.get(name, notset)))
  248. # Not all Mapping types support indexing, but MutableMapping doesn't support TypedDict
  249. del dic[name] # type: ignore[attr-defined]
  250. def setenv(self, name: str, value: str, prepend: str | None = None) -> None:
  251. """Set environment variable ``name`` to ``value``.
  252. If ``prepend`` is a character, read the current environment variable
  253. value and prepend the ``value`` adjoined with the ``prepend``
  254. character.
  255. """
  256. if not isinstance(value, str):
  257. warnings.warn( # type: ignore[unreachable]
  258. PytestWarning(
  259. f"Value of environment variable {name} type should be str, but got "
  260. f"{value!r} (type: {type(value).__name__}); converted to str implicitly"
  261. ),
  262. stacklevel=2,
  263. )
  264. value = str(value)
  265. if prepend and name in os.environ:
  266. value = value + prepend + os.environ[name]
  267. self.setitem(os.environ, name, value)
  268. def delenv(self, name: str, raising: bool = True) -> None:
  269. """Delete ``name`` from the environment.
  270. Raises ``KeyError`` if it does not exist, unless ``raising`` is set to
  271. False.
  272. """
  273. environ: MutableMapping[str, str] = os.environ
  274. self.delitem(environ, name, raising=raising)
  275. def syspath_prepend(self, path) -> None:
  276. """Prepend ``path`` to ``sys.path`` list of import locations."""
  277. if self._savesyspath is None:
  278. self._savesyspath = sys.path[:]
  279. sys.path.insert(0, str(path))
  280. # https://github.com/pypa/setuptools/blob/d8b901bc/docs/pkg_resources.txt#L162-L171
  281. # this is only needed when pkg_resources was already loaded by the namespace package
  282. if "pkg_resources" in sys.modules:
  283. import pkg_resources
  284. from pkg_resources import fixup_namespace_packages
  285. # Only issue deprecation warning if this call would actually have an
  286. # effect for this specific path.
  287. if (
  288. hasattr(pkg_resources, "_namespace_packages")
  289. and pkg_resources._namespace_packages
  290. ):
  291. path_obj = Path(str(path))
  292. for ns_pkg in pkg_resources._namespace_packages:
  293. if ns_pkg is None:
  294. continue
  295. ns_pkg_path = path_obj / ns_pkg.replace(".", os.sep)
  296. if ns_pkg_path.is_dir():
  297. warnings.warn(
  298. MONKEYPATCH_LEGACY_NAMESPACE_PACKAGES, stacklevel=2
  299. )
  300. break
  301. fixup_namespace_packages(str(path))
  302. # A call to syspathinsert() usually means that the caller wants to
  303. # import some dynamically created files, thus with python3 we
  304. # invalidate its import caches.
  305. # This is especially important when any namespace package is in use,
  306. # since then the mtime based FileFinder cache (that gets created in
  307. # this case already) gets not invalidated when writing the new files
  308. # quickly afterwards.
  309. from importlib import invalidate_caches
  310. invalidate_caches()
  311. def chdir(self, path: str | os.PathLike[str]) -> None:
  312. """Change the current working directory to the specified path.
  313. :param path:
  314. The path to change into.
  315. """
  316. if self._cwd is None:
  317. self._cwd = os.getcwd()
  318. os.chdir(path)
  319. def undo(self) -> None:
  320. """Undo previous changes.
  321. This call consumes the undo stack. Calling it a second time has no
  322. effect unless you do more monkeypatching after the undo call.
  323. There is generally no need to call `undo()`, since it is
  324. called automatically during tear-down.
  325. .. note::
  326. The same `monkeypatch` fixture is used across a
  327. single test function invocation. If `monkeypatch` is used both by
  328. the test function itself and one of the test fixtures,
  329. calling `undo()` will undo all of the changes made in
  330. both functions.
  331. Prefer to use :meth:`context() <pytest.MonkeyPatch.context>` instead.
  332. """
  333. for obj, name, value in reversed(self._setattr):
  334. if value is not notset:
  335. setattr(obj, name, value)
  336. else:
  337. delattr(obj, name)
  338. self._setattr[:] = []
  339. for dictionary, key, value in reversed(self._setitem):
  340. if value is notset:
  341. try:
  342. # Not all Mapping types support indexing, but MutableMapping doesn't support TypedDict
  343. del dictionary[key] # type: ignore[attr-defined]
  344. except KeyError:
  345. pass # Was already deleted, so we have the desired state.
  346. else:
  347. # Not all Mapping types support indexing, but MutableMapping doesn't support TypedDict
  348. dictionary[key] = value # type: ignore[index]
  349. self._setitem[:] = []
  350. if self._savesyspath is not None:
  351. sys.path[:] = self._savesyspath
  352. self._savesyspath = None
  353. if self._cwd is not None:
  354. os.chdir(self._cwd)
  355. self._cwd = None