From e36402a83041007b34a111fb20ede88abf4cb223 Mon Sep 17 00:00:00 2001 From: Zachary Ware Date: Mon, 6 Jul 2015 23:58:12 -0500 Subject: [PATCH 1/2] Fix usage of the default role. The changes to Doc/library/unittest.mock.rst are almost entirely a selective backport of the 3.5 page. --- Doc/c-api/structures.rst | 7 ++-- Doc/library/unittest.mock.rst | 70 +++++++++++++++++------------------ 2 files changed, 39 insertions(+), 38 deletions(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index b925a617043..e9e8add6c1d 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -60,7 +60,7 @@ the definition of all other Python objects. .. c:macro:: Py_TYPE(o) - This macro is used to access the `ob_type` member of a Python object. + This macro is used to access the :attr:`ob_type` member of a Python object. It expands to:: (((PyObject*)(o))->ob_type) @@ -68,7 +68,8 @@ the definition of all other Python objects. .. c:macro:: Py_REFCNT(o) - This macro is used to access the `ob_refcnt` member of a Python object. + This macro is used to access the :attr:`ob_refcnt` member of a Python + object. It expands to:: (((PyObject*)(o))->ob_refcnt) @@ -76,7 +77,7 @@ the definition of all other Python objects. .. c:macro:: Py_SIZE(o) - This macro is used to access the `ob_size` member of a Python object. + This macro is used to access the :attr:`ob_size` member of a Python object. It expands to:: (((PyVarObject*)(o))->ob_size) diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst index 70fe38ac72a..8346cb922ee 100644 --- a/Doc/library/unittest.mock.rst +++ b/Doc/library/unittest.mock.rst @@ -181,71 +181,71 @@ The Mock Class -------------- -`Mock` is a flexible mock object intended to replace the use of stubs and +:class:`Mock` is a flexible mock object intended to replace the use of stubs and test doubles throughout your code. Mocks are callable and create attributes as new mocks when you access them [#]_. Accessing the same attribute will always return the same mock. Mocks record how you use them, allowing you to make assertions about what your code has done to them. -:class:`MagicMock` is a subclass of `Mock` with all the magic methods +:class:`MagicMock` is a subclass of :class:`Mock` with all the magic methods pre-created and ready to use. There are also non-callable variants, useful when you are mocking out objects that aren't callable: :class:`NonCallableMock` and :class:`NonCallableMagicMock` The :func:`patch` decorators makes it easy to temporarily replace classes -in a particular module with a `Mock` object. By default `patch` will create -a `MagicMock` for you. You can specify an alternative class of `Mock` using -the `new_callable` argument to `patch`. +in a particular module with a :class:`Mock` object. By default :func:`patch` will create +a :class:`MagicMock` for you. You can specify an alternative class of :class:`Mock` using +the *new_callable* argument to :func:`patch`. .. class:: Mock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, **kwargs) - Create a new `Mock` object. `Mock` takes several optional arguments + Create a new :class:`Mock` object. :class:`Mock` takes several optional arguments that specify the behaviour of the Mock object: - * `spec`: This can be either a list of strings or an existing object (a + * *spec*: This can be either a list of strings or an existing object (a class or instance) that acts as the specification for the mock object. If you pass in an object then a list of strings is formed by calling dir on the object (excluding unsupported magic attributes and methods). - Accessing any attribute not in this list will raise an `AttributeError`. + Accessing any attribute not in this list will raise an :exc:`AttributeError`. - If `spec` is an object (rather than a list of strings) then + If *spec* is an object (rather than a list of strings) then :attr:`~instance.__class__` returns the class of the spec object. This - allows mocks to pass `isinstance` tests. + allows mocks to pass :func:`isinstance` tests. - * `spec_set`: A stricter variant of `spec`. If used, attempting to *set* + * *spec_set*: A stricter variant of *spec*. If used, attempting to *set* or get an attribute on the mock that isn't on the object passed as - `spec_set` will raise an `AttributeError`. + *spec_set* will raise an :exc:`AttributeError`. - * `side_effect`: A function to be called whenever the Mock is called. See + * *side_effect*: A function to be called whenever the Mock is called. See the :attr:`~Mock.side_effect` attribute. Useful for raising exceptions or dynamically changing return values. The function is called with the same arguments as the mock, and unless it returns :data:`DEFAULT`, the return value of this function is used as the return value. - Alternatively `side_effect` can be an exception class or instance. In + Alternatively *side_effect* can be an exception class or instance. In this case the exception will be raised when the mock is called. - If `side_effect` is an iterable then each call to the mock will return + If *side_effect* is an iterable then each call to the mock will return the next value from the iterable. - A `side_effect` can be cleared by setting it to `None`. + A *side_effect* can be cleared by setting it to ``None``. - * `return_value`: The value returned when the mock is called. By default + * *return_value*: The value returned when the mock is called. By default this is a new Mock (created on first access). See the :attr:`return_value` attribute. - * `wraps`: Item for the mock object to wrap. If `wraps` is not None then + * *wraps*: Item for the mock object to wrap. If *wraps* is not None then calling the Mock will pass the call through to the wrapped object (returning the real result). Attribute access on the mock will return a Mock object that wraps the corresponding attribute of the wrapped object (so attempting to access an attribute that doesn't exist will - raise an `AttributeError`). + raise an :exc:`AttributeError`). - If the mock has an explicit `return_value` set then calls are not passed - to the wrapped object and the `return_value` is returned instead. + If the mock has an explicit *return_value* set then calls are not passed + to the wrapped object and the *return_value* is returned instead. - * `name`: If the mock has a name then it will be used in the repr of the + * *name*: If the mock has a name then it will be used in the repr of the mock. This can be useful for debugging. The name is propagated to child mocks. @@ -1032,25 +1032,25 @@ patch default because it can be dangerous. With it switched on you can write passing tests against APIs that don't actually exist! - Patch can be used as a `TestCase` class decorator. It works by + Patch can be used as a :class:`TestCase` class decorator. It works by decorating each test method in the class. This reduces the boilerplate - code when your test methods share a common patchings set. `patch` finds - tests by looking for method names that start with `patch.TEST_PREFIX`. - By default this is `test`, which matches the way `unittest` finds tests. - You can specify an alternative prefix by setting `patch.TEST_PREFIX`. + code when your test methods share a common patchings set. :func:`patch` finds + tests by looking for method names that start with ``patch.TEST_PREFIX``. + By default this is ``'test'``, which matches the way :mod:`unittest` finds tests. + You can specify an alternative prefix by setting ``patch.TEST_PREFIX``. Patch can be used as a context manager, with the with statement. Here the patching applies to the indented block after the with statement. If you use "as" then the patched object will be bound to the name after the - "as"; very useful if `patch` is creating a mock object for you. + "as"; very useful if :func:`patch` is creating a mock object for you. - `patch` takes arbitrary keyword arguments. These will be passed to - the `Mock` (or `new_callable`) on construction. + :func:`patch` takes arbitrary keyword arguments. These will be passed to + the :class:`Mock` (or *new_callable*) on construction. - `patch.dict(...)`, `patch.multiple(...)` and `patch.object(...)` are + ``patch.dict(...)``, ``patch.multiple(...)`` and ``patch.object(...)`` are available for alternate use-cases. -`patch` as function decorator, creating the mock for you and passing it into +:func:`patch` as function decorator, creating the mock for you and passing it into the decorated function: >>> @patch('__main__.SomeClass') @@ -1392,15 +1392,15 @@ method of a :class:`TestCase`: ... assert package.module.Class is self.MockClass ... - As an added bonus you no longer need to keep a reference to the `patcher` + As an added bonus you no longer need to keep a reference to the ``patcher`` object. It is also possible to stop all patches which have been started by using -`patch.stopall`. +:func:`patch.stopall`. .. function:: patch.stopall - Stop all active patches. Only stops patches started with `start`. + Stop all active patches. Only stops patches started with ``start``. TEST_PREFIX From 3d3aedc8ba2d7e97859b408c8ea3565c68364f0c Mon Sep 17 00:00:00 2001 From: Zachary Ware Date: Tue, 7 Jul 2015 00:07:25 -0500 Subject: [PATCH 2/2] Fix usage of the default role. --- Doc/library/sys.rst | 2 +- Doc/library/test.rst | 6 +++--- Doc/whatsnew/3.5.rst | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 545e6742c13..bb9bdc86a13 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -1100,7 +1100,7 @@ always available. pass # The following line will fail with a RuntimeError, because - # `wrapper` creates a `wrap(coro)` coroutine: + # ``wrapper`` creates a ``wrap(coro)`` coroutine: foo() See also :func:`get_coroutine_wrapper`. diff --git a/Doc/library/test.rst b/Doc/library/test.rst index 8f2df7c15a7..f7ad475402e 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -570,9 +570,9 @@ The :mod:`test.support` module defines the following functions: .. function:: detect_api_mismatch(ref_api, other_api, *, ignore=()): - Returns the set of attributes, functions or methods of `ref_api` not - found on `other_api`, except for a defined list of items to be - ignored in this check specified in `ignore`. + Returns the set of attributes, functions or methods of *ref_api* not + found on *other_api*, except for a defined list of items to be + ignored in this check specified in *ignore*. By default this skips private attributes beginning with '_' but includes all magic methods, i.e. those starting and ending in '__'. diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst index 9713a98f368..a6d48598e9c 100644 --- a/Doc/whatsnew/3.5.rst +++ b/Doc/whatsnew/3.5.rst @@ -1086,7 +1086,7 @@ Changes in the Python API * The :mod:`socket` module now exports the CAN_RAW_FD_FRAMES constant on linux 3.6 and greater. -* The `pygettext.py` Tool now uses the standard +NNNN format for timezones in +* The ``pygettext.py`` Tool now uses the standard +NNNN format for timezones in the POT-Creation-Date header. * The :mod:`smtplib` module now uses :data:`sys.stderr` instead of previous