diff options
Diffstat (limited to 'Doc/library')
| -rw-r--r-- | Doc/library/hashlib-blake2.rst | 22 | ||||
| -rw-r--r-- | Doc/library/io.rst | 21 | ||||
| -rw-r--r-- | Doc/library/logging.rst | 10 | ||||
| -rw-r--r-- | Doc/library/re.rst | 6 | ||||
| -rw-r--r-- | Doc/library/socket.rst | 12 | ||||
| -rw-r--r-- | Doc/library/stdtypes.rst | 12 | ||||
| -rw-r--r-- | Doc/library/subprocess.rst | 6 | ||||
| -rw-r--r-- | Doc/library/sys.rst | 9 | ||||
| -rw-r--r-- | Doc/library/timeit.rst | 35 | ||||
| -rw-r--r-- | Doc/library/zipfile.rst | 4 |
10 files changed, 84 insertions, 53 deletions
diff --git a/Doc/library/hashlib-blake2.rst b/Doc/library/hashlib-blake2.rst index 436aa4f..1d28e06 100644 --- a/Doc/library/hashlib-blake2.rst +++ b/Doc/library/hashlib-blake2.rst @@ -3,8 +3,7 @@ :mod:`hashlib` --- BLAKE2 hash functions ======================================== -.. module:: hashlib - :synopsis: BLAKE2 hash function for Python +.. currentmodule:: hashlib .. sectionauthor:: Dmitry Chestnykh .. index:: @@ -26,9 +25,6 @@ Hash objects from this module follow the API of standard library's :mod:`hashlib` objects. -Module -====== - Creating hash objects --------------------- @@ -138,10 +134,10 @@ Maximum digest size that the hash function can output. Examples -======== +-------- Simple hashing --------------- +^^^^^^^^^^^^^^ To calculate hash of some data, you should first construct a hash object by calling the appropriate constructor function (:func:`blake2b` or @@ -176,7 +172,7 @@ update the hash: Using different digest sizes ----------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ BLAKE2 has configurable size of digests up to 64 bytes for BLAKE2b and up to 32 bytes for BLAKE2s. For example, to replace SHA-1 with BLAKE2b without changing @@ -208,7 +204,7 @@ produce different outputs even if the output length is the same: Keyed hashing -------------- +^^^^^^^^^^^^^ Keyed hashing can be used for authentication as a faster and simpler replacement for `Hash-based message authentication code @@ -261,7 +257,7 @@ in HMAC construction with :mod:`hmac` module:: Randomized hashing ------------------- +^^^^^^^^^^^^^^^^^^ By setting *salt* parameter users can introduce randomization to the hash function. Randomized hashing is useful for protecting against collision attacks @@ -317,7 +313,7 @@ initialization, rather than as an input to each compression function. Personalization ---------------- +^^^^^^^^^^^^^^^ Sometimes it is useful to force hash function to produce different digests for the same input for different purposes. Quoting the authors of the Skein hash @@ -362,7 +358,7 @@ keys from a single one. G9GtHFE1YluXY1zWPlYk1e/nWfu0WSEb0KRcjhDeP/o= Tree mode ---------- +^^^^^^^^^ Here's an example of hashing a minimal tree with two leaf nodes:: @@ -400,7 +396,7 @@ digest:: '3ad2a9b37c6070e374c7a8c508fe20ca86b6ed54e286e93a0318e95e881db5aa' Credits -======= +------- BLAKE2_ was designed by *Jean-Philippe Aumasson*, *Samuel Neves*, *Zooko Wilcox-O'Hearn*, and *Christian Winnerlein* based on SHA-3_ finalist BLAKE_ diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 4da6e09..c8ff5b8 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -477,7 +477,7 @@ I/O Base Classes A :exc:`BlockingIOError` is raised if the underlying raw stream is in non blocking-mode, and has no data available at the moment. - .. method:: read1(size=-1) + .. method:: read1([size]) Read and return up to *size* bytes, with at most one call to the underlying raw stream's :meth:`~RawIOBase.read` (or @@ -485,6 +485,9 @@ I/O Base Classes implementing your own buffering on top of a :class:`BufferedIOBase` object. + If *size* is ``-1`` (the default), an arbitrary number of bytes are + returned (more than zero unless EOF is reached). + .. method:: readinto(b) Read bytes into a pre-allocated, writable @@ -628,13 +631,16 @@ than raw I/O does. Return :class:`bytes` containing the entire contents of the buffer. - .. method:: read1() + .. method:: read1([size]) + + In :class:`BytesIO`, this is the same as :meth:`~BufferedIOBase.read`. - In :class:`BytesIO`, this is the same as :meth:`read`. + .. versionchanged:: 3.7 + The *size* argument is now optional. - .. method:: readinto1() + .. method:: readinto1(b) - In :class:`BytesIO`, this is the same as :meth:`readinto`. + In :class:`BytesIO`, this is the same as :meth:`~BufferedIOBase.readinto`. .. versionadded:: 3.5 @@ -664,12 +670,15 @@ than raw I/O does. Read and return *size* bytes, or if *size* is not given or negative, until EOF or if the read call would block in non-blocking mode. - .. method:: read1(size) + .. method:: read1([size]) Read and return up to *size* bytes with only one call on the raw stream. If at least one byte is buffered, only buffered bytes are returned. Otherwise, one raw stream read call is made. + .. versionchanged:: 3.7 + The *size* argument is now optional. + .. class:: BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE) diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 6098878..d03cc50 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -1023,7 +1023,7 @@ functions. handlers being added multiple times to the root logger, which can in turn lead to multiple messages for the same event. -.. function:: disable(lvl) +.. function:: disable(lvl=CRITICAL) Provides an overriding level *lvl* for all loggers which takes precedence over the logger's own level. When the need arises to temporarily throttle logging @@ -1036,6 +1036,14 @@ functions. overriding level, so that logging output again depends on the effective levels of individual loggers. + Note that if you have defined any custom logging level higher than + ``CRITICAL`` (this is not recommended), you won't be able to rely on the + default value for the *lvl* parameter, but will have to explicitly supply a + suitable value. + + .. versionchanged:: 3.7 + The *lvl* parameter was defaulted to level ``CRITICAL``. See Issue + #28524 for more information about this change. .. function:: addLevelName(lvl, levelName) diff --git a/Doc/library/re.rst b/Doc/library/re.rst index 7ef4cbe..adf3ddd 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -761,9 +761,9 @@ form. Unknown escapes in *pattern* consisting of ``'\'`` and an ASCII letter now are errors. - .. deprecated-removed:: 3.5 3.7 - Unknown escapes in *repl* consisting of ``'\'`` and an ASCII letter now raise - a deprecation warning and will be forbidden in Python 3.7. + .. versionchanged:: 3.7 + Unknown escapes in *repl* consisting of ``'\'`` and an ASCII letter + now are errors. .. function:: subn(pattern, repl, string, count=0, flags=0) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 9c10867..252b6db 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -664,6 +664,12 @@ The :mod:`socket` module also offers various network-related services: where the host byte order is the same as network byte order, this is a no-op; otherwise, it performs a 2-byte swap operation. + .. deprecated:: 3.7 + In case *x* does not fit in 16-bit unsigned integer, but does fit in a + positive C int, it is silently truncated to 16-bit unsigned integer. + This silent truncation feature is deprecated, and will raise an + exception in future versions of Python. + .. function:: htonl(x) @@ -678,6 +684,12 @@ The :mod:`socket` module also offers various network-related services: where the host byte order is the same as network byte order, this is a no-op; otherwise, it performs a 2-byte swap operation. + .. deprecated:: 3.7 + In case *x* does not fit in 16-bit unsigned integer, but does fit in a + positive C int, it is silently truncated to 16-bit unsigned integer. + This silent truncation feature is deprecated, and will raise an + exception in future versions of Python. + .. function:: inet_aton(ip_string) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 9a4f42c..d13fc3d 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2316,11 +2316,15 @@ the bytes type has an additional class method to read data in that format: This :class:`bytes` class method returns a bytes object, decoding the given string object. The string must contain two hexadecimal digits per - byte, with ASCII spaces being ignored. + byte, with ASCII whitespace being ignored. >>> bytes.fromhex('2Ef0 F1f2 ') b'.\xf0\xf1\xf2' + .. versionchanged:: 3.7 + :meth:`bytes.fromhex` now skips all ASCII whitespace in the string, + not just spaces. + A reverse conversion function exists to transform a bytes object into its hexadecimal representation. @@ -2384,11 +2388,15 @@ the bytearray type has an additional class method to read data in that format: This :class:`bytearray` class method returns bytearray object, decoding the given string object. The string must contain two hexadecimal digits - per byte, with ASCII spaces being ignored. + per byte, with ASCII whitespace being ignored. >>> bytearray.fromhex('2Ef0 F1f2 ') bytearray(b'.\xf0\xf1\xf2') + .. versionchanged:: 3.7 + :meth:`bytearray.fromhex` now skips all ASCII whitespace in the string, + not just spaces. + A reverse conversion function exists to transform a bytearray object into its hexadecimal representation. diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index ad2abe8..ea065b8 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -608,12 +608,6 @@ Instances of the :class:`Popen` class have the following methods: .. versionchanged:: 3.3 *timeout* was added. - .. deprecated:: 3.4 - - Do not use the *endtime* parameter. It is was unintentionally - exposed in 3.3 but was left undocumented as it was intended to be - private for internal use. Use *timeout* instead. - .. method:: Popen.communicate(input=None, timeout=None) Interact with process: Send data to stdin. Read data from stdout and stderr, diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index dd51ffd..54b99e0 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -404,6 +404,15 @@ always available. .. versionadded:: 3.4 +.. function:: getandroidapilevel() + + Return the build time API version of Android as an integer. + + Availability: Android. + + .. versionadded:: 3.7 + + .. function:: getcheckinterval() Return the interpreter's "check interval"; see :func:`setcheckinterval`. diff --git a/Doc/library/timeit.rst b/Doc/library/timeit.rst index 3b77276..4065808 100644 --- a/Doc/library/timeit.rst +++ b/Doc/library/timeit.rst @@ -28,11 +28,11 @@ can be used to compare three different expressions: .. code-block:: sh $ python3 -m timeit '"-".join(str(n) for n in range(100))' - 10000 loops, best of 3: 30.2 usec per loop + 10000 loops, best of 5: 30.2 usec per loop $ python3 -m timeit '"-".join([str(n) for n in range(100)])' - 10000 loops, best of 3: 27.5 usec per loop + 10000 loops, best of 5: 27.5 usec per loop $ python3 -m timeit '"-".join(map(str, range(100)))' - 10000 loops, best of 3: 23.2 usec per loop + 10000 loops, best of 5: 23.2 usec per loop This can be achieved from the :ref:`python-interface` with:: @@ -141,9 +141,8 @@ The module defines three convenience functions and a public class: This is a convenience function that calls :meth:`.timeit` repeatedly so that the total time >= 0.2 second, returning the eventual (number of loops, time taken for that number of loops). It calls - :meth:`.timeit` with *number* set to successive powers of ten (10, - 100, 1000, ...) up to a maximum of one billion, until the time taken - is at least 0.2 second, or the maximum is reached. + :meth:`.timeit` with increasing numbers from the sequence 1, 2, 5, + 10, 20, 50, ... until the time taken is at least 0.2 second. If *callback* is given and is not ``None``, it will be called after each trial with two arguments: ``callback(number, time_taken)``. @@ -197,7 +196,7 @@ Command-Line Interface When called as a program from the command line, the following form is used:: - python -m timeit [-n N] [-r N] [-u U] [-s S] [-t] [-c] [-h] [statement ...] + python -m timeit [-n N] [-r N] [-u U] [-s S] [-h] [statement ...] Where the following options are understood: @@ -222,20 +221,12 @@ Where the following options are understood: .. versionadded:: 3.3 -.. cmdoption:: -t, --time - - use :func:`time.time` (deprecated) - .. cmdoption:: -u, --unit=U - specify a time unit for timer output; can select usec, msec, or sec + specify a time unit for timer output; can select nsec, usec, msec, or sec .. versionadded:: 3.5 -.. cmdoption:: -c, --clock - - use :func:`time.clock` (deprecated) - .. cmdoption:: -v, --verbose print raw timing results; repeat for more digits precision @@ -276,9 +267,9 @@ It is possible to provide a setup statement that is executed only once at the be .. code-block:: sh $ python -m timeit -s 'text = "sample string"; char = "g"' 'char in text' - 10000000 loops, best of 3: 0.0877 usec per loop + 5000000 loops, best of 5: 0.0877 usec per loop $ python -m timeit -s 'text = "sample string"; char = "g"' 'text.find(char)' - 1000000 loops, best of 3: 0.342 usec per loop + 1000000 loops, best of 5: 0.342 usec per loop :: @@ -305,14 +296,14 @@ to test for missing and present object attributes: .. code-block:: sh $ python -m timeit 'try:' ' str.__bool__' 'except AttributeError:' ' pass' - 100000 loops, best of 3: 15.7 usec per loop + 20000 loops, best of 5: 15.7 usec per loop $ python -m timeit 'if hasattr(str, "__bool__"): pass' - 100000 loops, best of 3: 4.26 usec per loop + 50000 loops, best of 5: 4.26 usec per loop $ python -m timeit 'try:' ' int.__bool__' 'except AttributeError:' ' pass' - 1000000 loops, best of 3: 1.43 usec per loop + 200000 loops, best of 5: 1.43 usec per loop $ python -m timeit 'if hasattr(int, "__bool__"): pass' - 100000 loops, best of 3: 2.23 usec per loop + 100000 loops, best of 5: 2.23 usec per loop :: diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst index 9056489..97d31d9 100644 --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -672,18 +672,22 @@ Command-line options ~~~~~~~~~~~~~~~~~~~~ .. cmdoption:: -l <zipfile> + --list <zipfile> List files in a zipfile. .. cmdoption:: -c <zipfile> <source1> ... <sourceN> + --create <zipfile> <source1> ... <sourceN> Create zipfile from source files. .. cmdoption:: -e <zipfile> <output_dir> + --extract <zipfile> <output_dir> Extract zipfile into target directory. .. cmdoption:: -t <zipfile> + --test <zipfile> Test whether the zipfile is valid or not. |