Deploying to gh-pages from @ 29fd773 🚀

Author: mattwang44

.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: a722cb470f646be1f9759369084d7fc6
+config: b5e4c3d3c642f1dad50dbe268201b58a
 tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/library/dataclasses.rst.txt

@@ -613,7 +613,9 @@ methods will raise a :exc:`FrozenInstanceError` when invoked.
 
 There is a tiny performance penalty when using ``frozen=True``:
 :meth:`~object.__init__` cannot use simple assignment to initialize fields, and
-must use :meth:`!__setattr__`.
+must use :meth:`!object.__setattr__`.
+
+.. Make sure to not remove "object" from "object.__setattr__" in the above markup!
 
 .. _dataclasses-inheritance:
 

_sources/library/functions.rst.txt

@@ -604,9 +604,13 @@ are always available.  They are listed here in alphabetical order.
    will be used for both the global and the local variables.  If *globals* and
    *locals* are given, they are used for the global and local variables,
    respectively.  If provided, *locals* can be any mapping object.  Remember
-   that at the module level, globals and locals are the same dictionary. If exec
-   gets two separate objects as *globals* and *locals*, the code will be
-   executed as if it were embedded in a class definition.
+   that at the module level, globals and locals are the same dictionary.
+
+   .. note::
+
+      Most users should just pass a *globals* argument and never *locals*.
+      If exec gets two separate objects as *globals* and *locals*, the code
+      will be executed as if it were embedded in a class definition.
 
    If the *globals* dictionary does not contain a value for the key
    ``__builtins__``, a reference to the dictionary of the built-in module

_sources/library/hashlib.rst.txt

@@ -328,7 +328,7 @@ include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_.
    your application, read *Appendix A.2.2* of NIST-SP-800-132_. The answers
    on the `stackexchange pbkdf2 iterations question`_ explain in detail.
 
-   *dklen* is the length of the derived key. If *dklen* is ``None`` then the
+   *dklen* is the length of the derived key in bytes. If *dklen* is ``None`` then the
    digest size of the hash algorithm *hash_name* is used, e.g. 64 for SHA-512.
 
    >>> from hashlib import pbkdf2_hmac
@@ -357,7 +357,7 @@ include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_.
 
    *n* is the CPU/Memory cost factor, *r* the block size, *p* parallelization
    factor and *maxmem* limits memory (OpenSSL 1.1.0 defaults to 32 MiB).
-   *dklen* is the length of the derived key.
+   *dklen* is the length of the derived key in bytes.
 
    .. versionadded:: 3.6
 

_sources/library/itertools.rst.txt

@@ -690,18 +690,19 @@ loops that truncate the stream.
 
         def tee(iterable, n=2):
             iterator = iter(iterable)
-            empty_link = [None, None]  # Singly linked list: [value, link]
-            return tuple(_tee(iterator, empty_link) for _ in range(n))
+            shared_link = [None, None]
+            return tuple(_tee(iterator, shared_link) for _ in range(n))
 
         def _tee(iterator, link):
-            while True:
-                if link[1] is None:
-                    try:
-                        link[:] = [next(iterator), [None, None]]
-                    except StopIteration:
-                        return
-                value, link = link
-                yield value
+            try:
+                while True:
+                    if link[1] is None:
+                        link[0] = next(iterator)
+                        link[1] = [None, None]
+                    value, link = link
+                    yield value
+            except StopIteration:
+                return
 
    Once a :func:`tee` has been created, the original *iterable* should not be
    used anywhere else; otherwise, the *iterable* could get advanced without

_sources/library/marshal.rst.txt

@@ -10,7 +10,7 @@
 This module contains functions that can read and write Python values in a binary
 format.  The format is specific to Python, but independent of machine
 architecture issues (e.g., you can write a Python value to a file on a PC,
-transport the file to a Sun, and read it back there).  Details of the format are
+transport the file to a Mac, and read it back there).  Details of the format are
 undocumented on purpose; it may change between Python versions (although it
 rarely does). [#]_
 

_sources/library/socket.rst.txt

@@ -1584,7 +1584,8 @@ to sockets.
    Return a :term:`file object` associated with the socket.  The exact returned
    type depends on the arguments given to :meth:`makefile`.  These arguments are
    interpreted the same way as by the built-in :func:`open` function, except
-   the only supported *mode* values are ``'r'`` (default), ``'w'`` and ``'b'``.
+   the only supported *mode* values are ``'r'`` (default), ``'w'``, ``'b'``, or
+   a combination of those.
 
    The socket must be in blocking mode; it can have a timeout, but the file
    object's internal buffer may end up in an inconsistent state if a timeout

_sources/library/stdtypes.rst.txt

@@ -4556,7 +4556,7 @@ can be used interchangeably to index the same dictionary entry.
 
       Return a shallow copy of the dictionary.
 
-   .. classmethod:: fromkeys(iterable[, value])
+   .. classmethod:: fromkeys(iterable, value=None)
 
       Create a new dictionary with keys from *iterable* and values set to *value*.
 
@@ -4566,7 +4566,7 @@ can be used interchangeably to index the same dictionary entry.
       such as an empty list.  To get distinct values, use a :ref:`dict
       comprehension <dict>` instead.
 
-   .. method:: get(key[, default])
+   .. method:: get(key, default=None)
 
       Return the value for *key* if *key* is in the dictionary, else *default*.
       If *default* is not given, it defaults to ``None``, so that this method
@@ -4608,7 +4608,7 @@ can be used interchangeably to index the same dictionary entry.
 
       .. versionadded:: 3.8
 
-   .. method:: setdefault(key[, default])
+   .. method:: setdefault(key, default=None)
 
       If *key* is in the dictionary, return its value.  If not, insert *key*
       with a value of *default* and return *default*.  *default* defaults to

_sources/library/threading.rst.txt

@@ -594,14 +594,25 @@ and "recursion level" in addition to the locked/unlocked state used by primitive
 locks.  In the locked state, some thread owns the lock; in the unlocked state,
 no thread owns it.
 
-To lock the lock, a thread calls its :meth:`~RLock.acquire` method; this
-returns once the thread owns the lock.  To unlock the lock, a thread calls
-its :meth:`~Lock.release` method. :meth:`~Lock.acquire`/:meth:`~Lock.release`
-call pairs may be nested; only the final :meth:`~Lock.release` (the
-:meth:`~Lock.release` of the outermost pair) resets the lock to unlocked and
-allows another thread blocked in :meth:`~Lock.acquire` to proceed.
+Threads call a lock's :meth:`~RLock.acquire` method to lock it,
+and its :meth:`~Lock.release` method to unlock it.
 
-Reentrant locks also support the :ref:`context management protocol <with-locks>`.
+.. note::
+
+  Reentrant locks support the :ref:`context management protocol <with-locks>`,
+  so it is recommended to use :keyword:`with` instead of manually calling
+  :meth:`~RLock.acquire` and :meth:`~RLock.release`
+  to handle acquiring and releasing the lock for a block of code.
+
+RLock's :meth:`~RLock.acquire`/:meth:`~RLock.release` call pairs may be nested,
+unlike Lock's :meth:`~Lock.acquire`/:meth:`~Lock.release`. Only the final
+:meth:`~RLock.release` (the :meth:`~Lock.release` of the outermost pair) resets
+the lock to an unlocked state and allows another thread blocked in
+:meth:`~RLock.acquire` to proceed.
+
+:meth:`~RLock.acquire`/:meth:`~RLock.release` must be used in pairs: each acquire
+must have a release in the thread that has acquired the lock. Failing to
+call release as many times the lock has been acquired can lead to deadlock.
 
 
 .. class:: RLock()
@@ -620,25 +631,41 @@ Reentrant locks also support the :ref:`context management protocol <with-locks>`
 
       Acquire a lock, blocking or non-blocking.
 
-      When invoked without arguments: if this thread already owns the lock, increment
-      the recursion level by one, and return immediately.  Otherwise, if another
-      thread owns the lock, block until the lock is unlocked.  Once the lock is
-      unlocked (not owned by any thread), then grab ownership, set the recursion level
-      to one, and return.  If more than one thread is blocked waiting until the lock
-      is unlocked, only one at a time will be able to grab ownership of the lock.
-      There is no return value in this case.
+      .. seealso::
 
-      When invoked with the *blocking* argument set to ``True``, do the same thing as when
-      called without arguments, and return ``True``.
+         :ref:`Using RLock as a context manager <with-locks>`
+            Recommended over manual :meth:`!acquire` and :meth:`release` calls
+            whenever practical.
 
-      When invoked with the *blocking* argument set to ``False``, do not block.  If a call
-      without an argument would block, return ``False`` immediately; otherwise, do the
-      same thing as when called without arguments, and return ``True``.
 
-      When invoked with the floating-point *timeout* argument set to a positive
-      value, block for at most the number of seconds specified by *timeout*
-      and as long as the lock cannot be acquired.  Return ``True`` if the lock has
-      been acquired, ``False`` if the timeout has elapsed.
+      When invoked with the *blocking* argument set to ``True`` (the default):
+
+         * If no thread owns the lock, acquire the lock and return immediately.
+
+         * If another thread owns the lock, block until we are able to acquire
+           lock, or *timeout*, if set to a positive float value.
+
+         * If the same thread owns the lock, acquire the lock again, and
+           return immediately. This is the difference between :class:`Lock` and
+           :class:`!RLock`; :class:`Lock` handles this case the same as the previous,
+           blocking until the lock can be acquired.
+
+      When invoked with the *blocking* argument set to ``False``:
+
+         * If no thread owns the lock, acquire the lock and return immediately.
+
+         * If another thread owns the lock, return immediately.
+
+         * If the same thread owns the lock, acquire the lock again and return
+           immediately.
+
+      In all cases, if the thread was able to acquire the lock, return ``True``.
+      If the thread was unable to acquire the lock (i.e. if not blocking or
+      the timeout was reached) return ``False``.
+
+      If called multiple times, failing to call :meth:`~RLock.release` as many times
+      may lead to deadlock. Consider using :class:`!RLock` as a context manager rather than
+      calling acquire/release directly.
 
       .. versionchanged:: 3.2
          The *timeout* parameter is new.
@@ -654,7 +681,7 @@ Reentrant locks also support the :ref:`context management protocol <with-locks>`
 
       Only call this method when the calling thread owns the lock. A
       :exc:`RuntimeError` is raised if this method is called when the lock is
-      unlocked.
+      not acquired.
 
       There is no return value.
 

_sources/library/unittest.mock.rst.txt

@@ -410,13 +410,13 @@ the *new_callable* argument to :func:`patch`.
 
         This can be useful where you want to make a series of assertions that
         reuse the same object. Note that :meth:`reset_mock` *doesn't* clear the
-        return value, :attr:`side_effect` or any child attributes you have
+        :attr:`return_value`, :attr:`side_effect` or any child attributes you have
         set using normal assignment by default. In case you want to reset
-        *return_value* or :attr:`side_effect`, then pass the corresponding
+        :attr:`return_value` or :attr:`side_effect`, then pass the corresponding
         parameter as ``True``. Child mocks and the return value mock
         (if any) are reset as well.
 
-        .. note:: *return_value*, and :attr:`side_effect` are keyword-only
+        .. note:: *return_value*, and *side_effect* are keyword-only
                   arguments.
 
 
@@ -2535,40 +2535,16 @@ called incorrectly.
 
 Before I explain how auto-speccing works, here's why it is needed.
 
-:class:`Mock` is a very powerful and flexible object, but it suffers from two flaws
-when used to mock out objects from a system under test. One of these flaws is
-specific to the :class:`Mock` api and the other is a more general problem with using
-mock objects.
+:class:`Mock` is a very powerful and flexible object, but it suffers from a flaw which
+is general to mocking. If you refactor some of your code, rename members and so on, any
+tests for code that is still using the *old api* but uses mocks instead of the real
+objects will still pass. This means your tests can all pass even though your code is
+broken.
 
-First the problem specific to :class:`Mock`. :class:`Mock` has two assert methods that are
-extremely handy: :meth:`~Mock.assert_called_with` and
-:meth:`~Mock.assert_called_once_with`.
+.. versionchanged:: 3.5
 
-    >>> mock = Mock(name='Thing', return_value=None)
-    >>> mock(1, 2, 3)
-    >>> mock.assert_called_once_with(1, 2, 3)
-    >>> mock(1, 2, 3)
-    >>> mock.assert_called_once_with(1, 2, 3)
-    Traceback (most recent call last):
-     ...
-    AssertionError: Expected 'mock' to be called once. Called 2 times.
-
-Because mocks auto-create attributes on demand, and allow you to call them
-with arbitrary arguments, if you misspell one of these assert methods then
-your assertion is gone:
-
-.. code-block:: pycon
-
-    >>> mock = Mock(name='Thing', return_value=None)
-    >>> mock(1, 2, 3)
-    >>> mock.assret_called_once_with(4, 5, 6)  # Intentional typo!
-
-Your tests can pass silently and incorrectly because of the typo.
-
-The second issue is more general to mocking. If you refactor some of your
-code, rename members and so on, any tests for code that is still using the
-*old api* but uses mocks instead of the real objects will still pass. This
-means your tests can all pass even though your code is broken.
+    Before 3.5, tests with a typo in the word assert would silently pass when they should
+    raise an error. You can still achieve this behavior by passing ``unsafe=True`` to Mock.
 
 Note that this is another reason why you need integration tests as well as
 unit tests. Testing everything in isolation is all fine and dandy, but if you