Mailman 3 August 2013 - docs

[issue16805] when building docs on Debian 7 --> ERROR: Error in "note" directive
by Tshepang Lekhonkhobe March 13, 2014

March 13, 2014

New submission from Tshepang Lekhonkhobe: I am running Debian 7, which has sphinx is1.1.3+dfsg-4. When I run $ python tools/sphinx-build.py -bhtml . build/ I get a whole bunch of errors: Making output directory... Running Sphinx v1.1.3 loading pickled environment... not yet created building [html]: targets for 435 source files that are out of date updating environment: 435 added, 0 changed, 0 removed reading sources... [100%] whatsnew/index /home/wena/src/python/cpython/Doc/c-api/arg.rst:47: ERROR: Error in "note" directive: invalid option block. .. note:: For all ``#`` variants of formats (``s#``, ``y#``, etc.), the type of the length argument (int or :c:type:`Py_ssize_t`) is controlled by defining the macro :c:macro:`PY_SSIZE_T_CLEAN` before including :file:`Python.h`. If the macro was defined, length is a :c:type:`Py_ssize_t` rather than an :c:type:`int`. This behavior will change in a future Python version to only support :c:type:`Py_ssize_t` and drop :c:type:`int` support. It is best to always define :c:macro:`PY_SSIZE_T_CLEAN`. /home/wena/src/python/cpython/Doc/c-api/init.rst:547: ERROR: Error in "note" directive: invalid option block. .. note:: When only the main thread exists, no GIL operations are needed. This is a common situation (most Python programs do not use threads), and the lock operations slow the interpreter down a bit. Therefore, the lock is not created initially. This situation is equivalent to having acquired the lock: when there is only a single thread, all object accesses are safe. Therefore, when this function initializes the global interpreter lock, it also acquires it. Before the Python :mod:`_thread` module creates a new thread, knowing that either it has the lock or the lock hasn't been created yet, it calls :c:func:`PyEval_InitThreads`. When this call returns, it is guaranteed that the lock has been created and that the calling thread has acquired it. It is **not** safe to call this function when it is unknown which thread (if any) currently has the global interpreter lock. This function is not available when thread support is disabled at compile time. /home/wena/src/python/cpython/Doc/faq/library.rst:513: ERROR: Error in "note" directive: invalid option block. .. note:: To read and write binary data, it is mandatory to open the file in binary mode (here, passing ``"rb"`` to :func:`open`). If you use ``"r"`` instead (the default), the file will be open in text mode and ``f.read()`` will return :class:`str` objects rather than :class:`bytes` objects. /home/wena/src/python/cpython/Doc/library/fractions.rst:93: ERROR: Error in "note" directive: invalid option block. .. note:: From Python 3.2 onwards, you can also construct a :class:`Fraction` instance directly from a :class:`float`. /home/wena/src/python/cpython/Doc/library/fractions.rst:102: ERROR: Error in "note" directive: invalid option block. .. note:: From Python 3.2 onwards, you can also construct a :class:`Fraction` instance directly from a :class:`decimal.Decimal` instance. /home/wena/src/python/cpython/Doc/library/getopt.rst:12: ERROR: Error in "note" directive: invalid option block. .. note:: The :mod:`getopt` module is a parser for command line options whose API is designed to be familiar to users of the C :c:func:`getopt` function. Users who are unfamiliar with the C :c:func:`getopt` function or who would like to write less code and get better help and error messages should consider using the :mod:`argparse` module instead. /home/wena/src/python/cpython/Doc/library/io.rst:678: ERROR: Error in "warning" directive: invalid option block. .. warning:: :class:`BufferedRWPair` does not attempt to synchronize accesses to its underlying raw streams. You should not pass it the same object as reader and writer; use :class:`BufferedRandom` instead. /home/wena/src/python/cpython/Doc/library/logging.config.rst:144: ERROR: Error in "note" directive: invalid option block. .. note:: Because portions of the configuration are passed through :func:`eval`, use of this function may open its users to a security risk. While the function only binds to a socket on ``localhost``, and so does not accept connections from remote machines, there are scenarios where untrusted code could be run under the account of the process which calls :func:`listen`. Specifically, if the process calling :func:`listen` runs on a multi-user machine where users cannot trust each other, then a malicious user could arrange to run essentially arbitrary code in a victim user's process, simply by connecting to the victim's :func:`listen` socket and sending a configuration which runs whatever code the attacker wants to have executed in the victim's process. This is especially easy to do if the default port is used, but not hard even if a different port is used). To avoid the risk of this happening, use the ``verify`` argument to :func:`listen` to prevent unrecognised configurations from being applied. /home/wena/src/python/cpython/Doc/library/logging.config.rst:747: ERROR: Error in "note" directive: invalid option block. .. note:: Due to the use of :func:`eval` as described above, there are potential security risks which result from using the :func:`listen` to send and receive configurations via sockets. The risks are limited to where multiple users with no mutual trust run code on the same machine; see the :func:`listen` documentation for more information. /home/wena/src/python/cpython/Doc/library/os.rst:263: ERROR: Error in "note" directive: invalid option block. .. note:: On Mac OS X, :func:`getgroups` behavior differs somewhat from other Unix platforms. If the Python interpreter was built with a deployment target of :const:`10.5` or earlier, :func:`getgroups` returns the list of effective group ids associated with the current user process; this list is limited to a system-defined number of entries, typically 16, and may be modified by calls to :func:`setgroups` if suitably privileged. If built with a deployment target greater than :const:`10.5`, :func:`getgroups` returns the current group access list for the user associated with the effective user id of the process; the group access list may change over the lifetime of the process, it is not affected by calls to :func:`setgroups`, and its length is not limited to 16. The deployment target value, :const:`MACOSX_DEPLOYMENT_TARGET`, can be obtained with :func:`sysconfig.get_config_var`. /home/wena/src/python/cpython/Doc/library/pkgutil.rst:148: ERROR: Error in "note" directive: invalid option block. .. note:: Only works for a :term:`finder` which defines an ``iter_modules()`` method. This interface is non-standard, so the module also provides implementations for :class:`importlib.machinery.FileFinder` and :class:`zipimport.zipimporter`. /home/wena/src/python/cpython/Doc/library/pkgutil.rst:186: ERROR: Error in "note" directive: invalid option block. .. note:: Only works for a :term:`finder` which defines an ``iter_modules()`` method. This interface is non-standard, so the module also provides implementations for :class:`importlib.machinery.FileFinder` and :class:`zipimport.zipimporter`. /home/wena/src/python/cpython/Doc/library/socket.rst:728: ERROR: Error in "note" directive: invalid option block. .. note:: :meth:`close()` releases the resource associated with a connection but does not necessarily close the connection immediately. If you want to close the connection in a timely fashion, call :meth:`shutdown()` before :meth:`close()`. /home/wena/src/python/cpython/Doc/library/ssl.rst:609: ERROR: Error in "note" directive: invalid option block. .. note:: To validate a certificate for a particular service, you can use the :func:`match_hostname` function. /home/wena/src/python/cpython/Doc/library/sys.rst:245: ERROR: Error in "note" directive: invalid option block. .. note:: If a :ref:`virtual environment <venv-def>` is in effect, this value will be changed in ``site.py`` to point to the virtual environment. The value for the Python installation will still be available, via :data:`base_exec_prefix`. /home/wena/src/python/cpython/Doc/library/test.rst:201: ERROR: Error in "note" directive: invalid option block. .. note:: :mod:`test.support` is not a public module. It is documented here to help Python developers write tests. The API of this module is subject to change without backwards compatibility concerns between releases. looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] whatsnew/index writing additional files... genindex py-modindex search download index opensearch copying images... [100%] library/turtle-star.png copying static files... done dumping search index... done dumping object inventory... done build succeeded, 16 warnings. ---------- assignee: docs@python components: Documentation messages: 178443 nosy: docs@python, tshepang priority: normal severity: normal status: open title: when building docs on Debian 7 --> ERROR: Error in "note" directive versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16805> _______________________________________

7 27

[issue12354] packaging.pypi.simple docs use both client and crawler variable, which might be confusing
by Filip Gruszczyński March 13, 2014

March 13, 2014

New submission from Filip Gruszczyński <gruszczy(a)gmail.com>: In documentation for packaging.pypi.simple in first code snippet crawler variable is created on which further operations will be performed. However in all next snippets there is client variable, which is a little confusing on first sight. This could be consistent throughout the whole page. ---------- assignee: docs@python components: Distutils2, Documentation messages: 138538 nosy: alexis, docs@python, eric.araujo, gruszczy priority: normal severity: normal status: open title: packaging.pypi.simple docs use both client and crawler variable, which might be confusing versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12354> _______________________________________

4 9

[issue15231] update PyPI upload doc to say --no-raw passed to rst2html.py
by Chris Jerdonek March 12, 2014

March 12, 2014

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: I had an issue whereby my reST long_description wasn't getting rendered as HTML when uploaded to PyPI. Following the instructions here did not work as-is: http://docs.python.org/dev/distutils/uploading.html#pypi-package-display It seems that PyPI passes --no-raw (no HTML allowed) to rst2html.py, in which case the guidance would be better updated to read-- $ python setup.py --long-description | rst2html.py --no-raw > output.html ---------- assignee: docs@python components: Documentation keywords: easy messages: 164445 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: update PyPI upload doc to say --no-raw passed to rst2html.py versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15231> _______________________________________

5 39

[issue13530] Docs for os.lseek neglect to mention what it returns
by Ned Batchelder March 11, 2014

March 11, 2014

New submission from Ned Batchelder <ned(a)nedbatchelder.com>: The docs for os.lseek don't make any mention of its return value. I believe it's the new offset in the file, but I'm not sure if there are other subtleties to be mentioned. ---------- assignee: docs@python components: Documentation messages: 148861 nosy: docs@python, nedbat priority: normal severity: normal status: open title: Docs for os.lseek neglect to mention what it returns versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13530> _______________________________________

9 10

[issue14995] PyLong_FromString documentation should state that the string must be null-terminated
by Ryan Kelly March 2, 2014

March 2, 2014

New submission from Ryan Kelly <ryan(a)rfk.id.au>: PyLong_FromString will raise a ValueError if the given string doesn't contain a null byte after the digits. For example, this will result in a ValueError char *pend; PyLong_FromString("1234 extra", &pend, 10) While this will successfully read the number and set the pointer to the extra data: char *pend; PyLong_FromString("1234\0extra", &pend, 10) The requirement for a null-terminated string of digits is not clear from the docs. Suggested re-wording attached. ---------- assignee: docs@python components: Documentation files: PyLong_FromString-doc.patch keywords: patch messages: 162242 nosy: docs@python, rfk priority: normal severity: normal status: open title: PyLong_FromString documentation should state that the string must be null-terminated Added file: http://bugs.python.org/file25812/PyLong_FromString-doc.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14995> _______________________________________

2 1

[issue13663] pootle.python.org is outdated.
by INADA Naoki Feb. 16, 2014

Feb. 16, 2014

New submission from INADA Naoki <songofacandy(a)gmail.com>: I am one of Japanese translate of Python documents. We have done translating Python 2.7 document and will start translating Python 3.2 or 3.3. I want to use sphinx-i18n and pootle to translate. But http://pootle.python.org/ is very outdated. Anyone can update the site? If nobody maintain the site, could I create Python Document project at http://pootle.locamotion.org/ ? ---------- assignee: docs@python components: Documentation messages: 150261 nosy: docs@python, naoki priority: normal severity: normal status: open title: pootle.python.org is outdated. versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13663> _______________________________________

8 10

[issue14515] tempfile.TemporaryDirectory documented as returning object but returns name
by R. David Murray Feb. 5, 2014

Feb. 5, 2014

New submission from R. David Murray <rdmurray(a)bitdance.com>: The title pretty much says it all. I believe the behavior is correct (more useful than returning an object that is only useful for obtaining the name) even though it is unusual for context managers. In any case there is plenty of code using the existing behavior, so I think this is a doc bug. ---------- assignee: docs@python components: Documentation messages: 157635 nosy: docs@python, r.david.murray priority: normal severity: normal stage: needs patch status: open title: tempfile.TemporaryDirectory documented as returning object but returns name type: behavior versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14515> _______________________________________

6 9

[issue17727] document that some distributions change site.py defaults
by Georg Brandl Jan. 29, 2014

Jan. 29, 2014

New submission from Georg Brandl: >From the docs@ list: """ Dear all, the first paragraph of the documentation for the site module states that site.py constructs four directories using a head and tail part, and that one of the tail parts would be lib/pythonX.Y/site-packages on UNIX/Mac. However, in my Python 3.2 installation on Ubuntu 12.04 this is actually lib/python3/dist-packages (so no .Y and a different subdirectory) ! This is also stated in the module’s doc string. I don’t know why the Python documentation says something else, but that should be fixed. """ Attached a patch to explain why the defaults may look different on some distributions. Please review. ---------- assignee: docs@python components: Documentation files: site-patch.diff keywords: patch messages: 186897 nosy: barry, docs@python, doko, georg.brandl priority: normal severity: normal stage: patch review status: open title: document that some distributions change site.py defaults type: enhancement versions: Python 2.7, Python 3.3, Python 3.4 Added file: http://bugs.python.org/file29849/site-patch.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17727> _______________________________________

2 2

[issue12704] Language References does not specify exception raised by final yield()
by Nikolaus Rath Jan. 27, 2014

Jan. 27, 2014

New submission from Nikolaus Rath <Nikolaus(a)rath.org>: >From http://docs.python.org/reference/simple_stmts.html#the-yield-statement: "As of Python version 2.5, the yield statement is now allowed in the try clause of a try ... finally construct. If the generator is not resumed before it is finalized (by reaching a zero reference count or by being garbage collected), the generator-iterator’s close() method will be called, allowing any pending finally clauses to execute." This strongly suggests that the last-executed yield statement will raise an exception if the generator is closed. If this is the case, it would be great if the documentation could be extended to say what exception is raised. If this is not the case, it would be great if whatever magic is happening could be documented as well. ---------- assignee: docs@python components: Documentation messages: 141724 nosy: Nikratio, docs@python priority: normal severity: normal status: open title: Language References does not specify exception raised by final yield() type: feature request versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________

8 18

[issue17811] Improve os.readv() and os.writev() documentation and docstring
by Nikolaus Rath Jan. 19, 2014

Jan. 19, 2014

New submission from Nikolaus Rath: The os.writev and os.readv functions are currently documented as: os.writev(fd, buffers) Write the contents of buffers to file descriptor fd, where buffers is an arbitrary sequence of buffers. Returns the total number of bytes written. os.readv(fd, buffers) Read from a file descriptor into a number of writable buffers. buffers is an arbitrary sequence of writable buffers. Returns the total number of bytes read. This is rather confusing, mostly because it's not clear what can be passed as *buffer* (since buffer objects don't exist in Python 3 anymore), and (as a consequence) how the input will be distributed among the list of buffers. Reading the code, it seems to me that any object that implements the buffer protocol would be fine, but that still doesn't help much in practice. From the memoryview documentation, I can infer that `bytes` implements the buffer protocol, but is also immutable, so how can something be written into it? I'd be happy to write a patch to the documentation, but someone would need to explain to me first what kind of buffers are actually acceptable (and I suspect this will be different for readv and writev). ---------- assignee: docs@python components: Documentation messages: 187526 nosy: Nikratio, docs@python priority: normal severity: normal status: open title: Improve os.readv() and os.writev() documentation and docstring type: enhancement versions: Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17811> _______________________________________

5 9