[New-bugs-announce] [issue45215] Add docs for Mock name and parent args and deprecation warning when wrong args are passed

[Andrei Kulakov]

New submission from Andrei Kulakov <andrei.avk at gmail.com>:

Currently using *name* and *parent* args in Mock and MagicMock is problematic in a few ways:

*name*

 - any value can be passed silently but at a later time, any value except for an str will cause
   an exception when repr() or str() on the mock object is done.

 - a string name can be passed but will not be equal to the respective attr value:
   Mock(name='foo').name != 'foo', as users would expect. (this should be documented).

*parent*

 - any value can be passed but, similarly to *name*, will cause an exception when str() or
   repr() is done on the object.

 - this arg is not documented so users will expect it to be set as an attr, but instead the
   attribute is going to be a Mock instance. [1]


I propose to fix these issues by:

 - checking the types that are passed in and display a DeprecationWarning if types are wrong.
 (note that this check should be fast because at first value can be compared to None default,
 which is what it's going to be in vast majority of cases, and isinstance() check is only done
 after that.) (in 3.11)

 - in 3.12, convert warnings into TypeError.

 - Document that *name* attribute will be a Mock instance.

 - Document that *name* argument needs to be a string.

 - Document *parent* argument.

 - In the docs for the two args, point to `configure_mock()` method for setting them to
   arbitrary values.

(Note that other args for Mock() have more specialized names and are much less likely to cause
similar issues.)

[1] https://bugs.python.org/issue39222

----------
components: Tests
messages: 401913
nosy: andrei.avk
priority: normal
severity: normal
status: open
title: Add docs for Mock name and parent args and deprecation warning when wrong args are passed
type: enhancement
versions: Python 3.11

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue45215>
_______________________________________