diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index 1f563ee0c49..b74c24d9fbc 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -576,7 +576,7 @@ In addition to the methods inherited from tuples, named tuples support three additional methods and one attribute. To prevent conflicts with field names, the method and attribute names start with an underscore. -.. method:: somenamedtuple._make(iterable) +.. classmethod:: somenamedtuple._make(iterable) Class method that makes a new instance from an existing sequence or iterable. diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst index 407efd0233a..c399bb78d7a 100644 --- a/Doc/library/csv.rst +++ b/Doc/library/csv.rst @@ -78,7 +78,7 @@ The :mod:`csv` module defines the following functions: A short usage example:: >>> import csv - >>> spamReader = csv.reader(open('eggs.csv'), delimiter=' ', quotechar='|') + >>> spamReader = csv.reader(open('eggs.csv', 'rb'), delimiter=' ', quotechar='|') >>> for row in spamReader: ... print ', '.join(row) Spam, Spam, Spam, Spam, Spam, Baked Beans @@ -116,7 +116,7 @@ The :mod:`csv` module defines the following functions: A short usage example:: >>> import csv - >>> spamWriter = csv.writer(open('eggs.csv', 'w'), delimiter=' ', + >>> spamWriter = csv.writer(open('eggs.csv', 'wb'), delimiter=' ', ... quotechar='|', quoting=csv.QUOTE_MINIMAL) >>> spamWriter.writerow(['Spam'] * 5 + ['Baked Beans']) >>> spamWriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam']) @@ -234,7 +234,7 @@ The :mod:`csv` module defines the following classes: An example for :class:`Sniffer` use:: - csvfile = open("example.csv") + csvfile = open("example.csv", "rb") dialect = csv.Sniffer().sniff(csvfile.read(1024)) csvfile.seek(0) reader = csv.reader(csvfile, dialect) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 38797ff6ac4..e3f30cb0d4a 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -6,11 +6,17 @@ :synopsis: Disassembler for Python bytecode. -The :mod:`dis` module supports the analysis of Python :term:`bytecode` by disassembling -it. Since there is no Python assembler, this module defines the Python assembly -language. The Python bytecode which this module takes as an input is defined -in the file :file:`Include/opcode.h` and used by the compiler and the -interpreter. +The :mod:`dis` module supports the analysis of CPython :term:`bytecode` by +disassembling it. The CPython bytecode which this module takes as an +input is defined in the file :file:`Include/opcode.h` and used by the compiler +and the interpreter. + +.. impl-detail:: + + Bytecode is an implementation detail of the CPython interpreter! No + guarantees are made that bytecode will not be added, removed, or changed + between versions of Python. Use of this module should not be considered to + work across Python VMs or Python releases. Example: Given the function :func:`myfunc`:: diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 92b443e352c..5b3a922ceb9 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -705,7 +705,7 @@ as internal buffering of data. This function is intended for low-level I/O. For normal usage, use the built-in function :func:`open`, which returns a "file object" with - :meth:`~file.read` and :meth:`~file.wprite` methods (and many more). To + :meth:`~file.read` and :meth:`~file.write` methods (and many more). To wrap a file descriptor in a "file object", use :func:`fdopen`. @@ -2035,8 +2035,9 @@ written in Python, such as a mail server's external command delivery program. The :mod:`subprocess` module provides more powerful facilities for spawning new processes and retrieving their results; using that module is preferable to using - this function. Use the :mod:`subprocess` module. Check especially the - :ref:`subprocess-replacements` section. + this function. See the + :ref:`subprocess-replacements` section in the :mod:`subprocess` documentation + for some helpful recipes. Availability: Unix, Windows. diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 39bef7c7868..188d3eb8431 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -799,7 +799,8 @@ string functions based on regular expressions. .. method:: str.capitalize() - Return a copy of the string with only its first character capitalized. + Return a copy of the string with its first character capitalized and the + rest lowercased. For 8-bit strings, this method is locale-dependent. diff --git a/Doc/library/test.rst b/Doc/library/test.rst index f447ea498e5..c73e23e6498 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -6,6 +6,13 @@ :synopsis: Regression tests package containing the testing suite for Python. .. sectionauthor:: Brett Cannon +.. note:: + The :mod:`test` package is meant for internal use by Python only. It is + documented for the benefit of the core developers of Python. Any use of + this package outside of Python's standard library is discouraged as code + mentioned here can change or be removed without notice between releases of + Python. + The :mod:`test` package contains all regression tests for Python as well as the modules :mod:`test.test_support` and :mod:`test.regrtest`. diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index 01f19a3d0ea..6a8ed0d3b38 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -319,8 +319,8 @@ impossible to detect the termination of alien threads. Return whether the thread is alive. - Roughly, a thread is alive from the moment the :meth:`start` method - returns until its :meth:`run` method terminates. The module function + This method returns ``True`` just before the :meth:`run` method starts + until just after the :meth:`run` method terminates. The module function :func:`.enumerate` returns a list of all alive threads. .. method:: isDaemon() diff --git a/Misc/NEWS b/Misc/NEWS index e4a73c933fd..02656443a21 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -437,6 +437,9 @@ Tests Documentation ------------- +- Issue #9255: Document that the 'test' package is for internal Python use + only. + - Issue #8909: Added the size of the bitmap used in the installer created by distutils' bdist_wininst. Patch by Anatoly Techtonik.