New submission from retnikt <retnikt(a)gmail.com>:
In the library documentation for argparse, the section for ArgumentParser.add_subparsers ( https://docs.python.org/3/library/argparse.html#sub-commands ) states that there is a parameter for 'action' with the description 'the basic type of action to be taken when this argument is encountered at the command line'. However, no such parameter actually exists, and passing it to the function causes very strange behaviour:
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/usr/lib/python3.6/argparse.py", line 1716, in add_subparsers
action = parsers_class(option_strings=[], **kwargs)
TypeError: __init__() got an unexpected keyword argument 'parser_class'
This line should be removed from the documentation. It is present in versions 3.4+ and 2.7
----------
assignee: docs@python
components: Documentation
messages: 348718
nosy: docs@python, retnikt
priority: normal
severity: normal
status: open
title: argparse subcommand docs has non-existent parameter "action"
type: behavior
versions: Python 2.7, Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9
_______________________________________
Python tracker <report(a)bugs.python.org>
<https://bugs.python.org/issue37717>
_______________________________________
New submission from Jake:
In the statistics module documentation, there is a note that states that
"The mean is strongly affected by outliers and is not a robust estimator for central location: the mean is not necessarily a typical example of the data points. For more robust, although less efficient, measures of central location, see median() and mode()"
https://docs.python.org/3/library/statistics.html
While I appreciate the intention, this is quite misleading. The implication is that the mean, median and mode are different ways to estimate one "central location", however, in reality they are very different things (albeit which refer to a similar notion).
The sample mean is an unbiased estimator of the true mean but it need not be unbiased as an estimator of the true median or modes and vice versa for the median and mode.
To make this clearer I would rephrase to
"The mean is strongly affected by outliers and is not necessarily representative of the central tendency of the data. For cases with large outliers or very low sample size, see median() and mode()"
Apologies if this is seen as frivolous, but statistics can be hard enough to remain very clear about even when the words are used precisely.
----------
assignee: docs@python
components: Documentation
messages: 236612
nosy: Journeyman08, docs@python
priority: normal
severity: normal
status: open
title: Misleading note in Statistics module documentation
type: enhancement
versions: Python 3.4
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue23522>
_______________________________________
New submission from Jonathan Fine <jfine2358(a)gmail.com>:
The docs contain a very useful page https://docs.python.org/3.5/glossary.html. However, the search feature does not index the glossary.
Thus, the search https://docs.python.org/3.5/search.html?q=iterable does not produce the helpful glossary entry
===
iterable
An object capable of returning its members one at a time. Examples of iterables include all sequence types (such as list, str, and tuple) and some non-sequence types like dict, file objects, and objects of any [...]
===
#788509 is the only docs issue I could find, whose title contains glossary. It gives insight into the thoughts then about the tutorial. In msg44460 Skip Montaro says (1) that the glossary is "for the tutorial", and (2) he'd like to improve links into the tutorial.
I suggest that part of the fix for this issue is on the home page page Glossary in the first grouping "Parts of the documentation."
----------
assignee: docs@python
components: Documentation
messages: 323503
nosy: docs@python, jfine2358
priority: normal
severity: normal
status: open
title: Docs search does not index glossary
type: behavior
versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8
_______________________________________
Python tracker <report(a)bugs.python.org>
<https://bugs.python.org/issue34398>
_______________________________________
New submission from Michael Amrhein <michael(a)adrhinum.de>:
The description of the "Format Specification Mini-Language" states for float and Decimal regarding presentation type 'f':
"The default precision is 6."
Regarding presentation type None it reads:
"Similar to 'g', except that fixed-point notation, when used, has at least one digit past the decimal point."
While both statements are accurate for float, they don't hold for Decimal.
In order to preserve the information about the decimal exponent, in both cases Decimal formatting displays as many fractional digits as dictated by it's exponent.
----------
assignee: docs@python
components: Documentation
messages: 358667
nosy: docs@python, mamrhein
priority: normal
severity: normal
status: open
title: Description of "Format Specification Mini-Language" not accurate for Decimal
type: behavior
versions: Python 3.6, Python 3.7, Python 3.8, Python 3.9
_______________________________________
Python tracker <report(a)bugs.python.org>
<https://bugs.python.org/issue39096>
_______________________________________
New submission from Karl O. Pinc <kop(a)karlpinc.com>:
Seems sane to put _some_ restrictions on the string representations of the Numeric classes. This would be a change to the Python language
specification.
Suggestions made in a pull request.
See the email thread:
Subject: Documenting Python's float.__str__()
https://mail.python.org/archives/list/python-dev@python.org/thread/FV22TKT3…
----------
assignee: docs@python
components: Documentation
messages: 360442
nosy: docs@python, kop
priority: normal
severity: normal
status: open
title: Document default numeric string formats
_______________________________________
Python tracker <report(a)bugs.python.org>
<https://bugs.python.org/issue39416>
_______________________________________
New submission from Guy Taylor <thebigguy.co.uk(a)gmail.com>:
The Python docs suggest that io.IOBase.truncate' should take a keyword argument of 'size'.
However this causes a 'TypeError':
TypeError: truncate() takes no keyword arguments
Suggest that the docs are changed to 'truncate(size)' or CPython is changed to allow the keyword.
http://docs.python.org/py3k/library/io.html?highlight=truncate#io.IOBase.tr…http://docs.python.org/library/io.html?highlight=truncate#io.IOBase.truncate
----------
assignee: docs@python
components: Documentation, Interpreter Core
files: test.py
messages: 158308
nosy: TheBiggerGuy, docs@python
priority: normal
severity: normal
status: open
title: TypeError: truncate() takes no keyword arguments
type: behavior
versions: Python 2.7, Python 3.2
Added file: http://bugs.python.org/file25219/test.py
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue14586>
_______________________________________
New submission from Brett Cannon:
https://docs.python.org/3/extending/extending.html#a-simple-example uses PyModule_Create() instead of PyModuleDef_Init().
----------
assignee: docs@python
components: Documentation
messages: 261398
nosy: brett.cannon, docs@python, eric.snow, ncoghlan
priority: normal
severity: normal
stage: needs patch
status: open
title: Update extending/embedding docs to new way to build modules in C
versions: Python 3.5, Python 3.6
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue26515>
_______________________________________
New submission from Joy Diamond <python.gem(a)gmail.com>:
This is a request to fix the documentation for __instancecheck__.
Please add the following:
"""
(Note that any object `x` is always considered to be an instance of
`type(x)`, and this cannot be overridden.)
"""
Consider the following program:
class M(type):
def __instancecheck__(m, t):
print('instancecheck(%s, %s)' % (m, t))
return False # LIE!
Test = M('Test', ((object,)), {})
something = Test()
print('Does *NOT* call __instancecheck__:')
print('isinstance(something, Test): %s' % isinstance(something, Test))
print()
print('Does call __instancecheck__:')
print('isinstance(0, Test): %s' % isinstance(0, Test))
Under python 2, python 3, and pypy, in all cases, the first examples does *NOT* call __instancecheck__.
You can see the optimization here:
https://github.com/python/cpython/blob/master/Objects/abstract.c#L2397-L2405
Which reads:
int
PyObject_IsInstance(PyObject *inst, PyObject *cls)
{
_Py_IDENTIFIER(__instancecheck__);
PyObject *checker;
/* Quick test for an exact match */
if (Py_TYPE(inst) == (PyTypeObject *)cls)
return 1;
I'm fine with the optimization -- I am not suggesting to get rid of it.
I just want the documentation to match the actual implementation.
The following documentation needs to be fixed:
https://docs.python.org/2/reference/datamodel.htmlhttps://docs.python.org/3/reference/datamodel.htmlhttps://www.python.org/dev/peps/pep-3119/
It took me half an hour to figure out why my version of __instancecheck__ was not working, as I tried to test it using the super simple code above ...
One of the best things about python is how accurate and consistent the documentation is.
This request is to keep these high standards.
----------
assignee: docs@python
components: Documentation
messages: 328658
nosy: docs@python, joydiamond
priority: normal
severity: normal
status: open
title: Fix documentation for __instancecheck__
type: enhancement
versions: Python 2.7, Python 3.8
_______________________________________
Python tracker <report(a)bugs.python.org>
<https://bugs.python.org/issue35083>
_______________________________________
New submission from Alex LordThorsen:
Had a friend get stuck on the CSV documentation. They didn't know what a CSV was (to start with) and couldn't find an example that made sense to them. they went to other sources to figure out how to read CSV files in the end.
I made this patch in the hope that starting out with a very minimal example file format followed by an example python read will make landing on the CSV docs easier to follow for new programmers.
----------
assignee: docs@python
components: Documentation
files: csv_documentation.patch
keywords: patch
messages: 260960
nosy: Alex.LordThorsen, docs@python
priority: normal
severity: normal
status: open
title: CSV documentation doesn't open with an example
versions: Python 3.6
Added file: http://bugs.python.org/file42040/csv_documentation.patch
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue26451>
_______________________________________
New submission from July Tikhonov:
In documentation of zipfile.ZipFile.write() there is following notice:
"There is no official file name encoding for ZIP files. If you have unicode file names, you must convert them to byte strings in your desired encoding before passing them to write()."
I understand it as that 'arcname' argument to write() shouldn't be of type str, but rather bytes.
But it is str that works, and bytes that does not:
$ ./python
Python 3.5.0a4+ (default:6f6e78931875, May 1 2015, 23:18:40)
[GCC 4.8.4] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import zipfile
>>> zf = zipfile.ZipFile('foo.zip', 'w')
>>> zf.write('python', 'a')
>>> zf.write('python', b'b')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/home/july/source/python/Lib/zipfile.py", line 1442, in write
zinfo = ZipInfo(arcname, date_time)
File "/home/july/source/python/Lib/zipfile.py", line 322, in __init__
null_byte = filename.find(chr(0))
TypeError: a bytes-like object is required, not 'str'
(ZipInfo ostensibly attempts to find a zero byte in the filename, but searches instead for a unicode character chr(0). There are several other places in ZipInfo class that assume filename being str rather than bytes.)
I consider this a documentation issue: the notice is misleading. Although maybe there is someone who wants to fix the behavior of ZipInfo to allow bytes filename.
----------
assignee: docs@python
components: Documentation
messages: 242355
nosy: docs@python, july
priority: normal
severity: normal
status: open
title: zipfile.ZipFile.write() does not accept bytes arcname
type: behavior
versions: Python 3.4, Python 3.5, Python 3.6
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue24110>
_______________________________________