New submission from Christopher Dunn <cdunn2001(a)gmail.com>:
This is an easy one.
When I zoom my browser in (with Ctrl+ or Apple+) the left-side navigation margin gets bigger and bigger, pushing the useful text off the screen. That has bothered me (and anyone else with 40+ year old eyes) ever since the switch to the newest doc format with Sphinx.
There is no fix that will satisfy everyone. People with perfect vision might like to zoom out (with Ctrl- or Apple-), since the margin currently gets smaller and smaller. But we need a compromise.
The relevant CSS, in default.css, is this:
div.bodywrapper {
margin: 0 0 0 230px;
}
If instead it were something like this:
div.bodywrapper {
margin: 0 0 0 10%;
}
then at least the navigation margin would stay the same size always.
If you really want it to grow and shrink, then you need some sort of javascript control of its position.
----------
assignee: docs@python
components: Documentation
messages: 126477
nosy: cdunn2001, docs@python
priority: normal
severity: normal
status: open
title: Simple CSS fix for left margin at docs.python.org
type: behavior
versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue10936>
_______________________________________
New submission from Mateusz Loskot <mateusz(a)loskot.net>:
The chapter '2. Defining New Types" in the Python 3.2 documentation [1] does not cover all important elements, especially in the subsection 2.1.4. Subclassing other types.
The accepted PEP 253 [2] provides much more detailed and thorough explanation for Python C API users willing to define and subclass new types, than the official manual.
I'd like to suggest update of the manual with information enclosed in the PEP 253. In fact, the PEP's sections like
* Preparing a type for subtyping
* Creating a subtype of a built-in type in C
could be copied with little editing, IMHO.
The PEP 253 really seems to be a must-read document for Python C API users.
[1] http://docs.python.org/release/3.2.2/extending/newtypes.html
[2] http://www.python.org/dev/peps/pep-0253/
----------
assignee: docs@python
components: Documentation
messages: 162480
nosy: docs@python, mloskot
priority: normal
severity: normal
status: open
title: Update Defining New Types chapter according to PEP 253
type: enhancement
versions: Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue15029>
_______________________________________
New submission from Jayanth Koushik:
The documentation for decimal.fma provides an example which fails to illustrate the most important feature of the function i.e. single rounding. In fact:
Decimal(2).fma(3, 5) == Decimal(2)*3 + 5
An example such as this would make it much more clear:
>>> getcontext().prec = 2
>>> getcontext().rounding = ROUND_DOWN
>>> Decimal('1.5')*Decimal('1.5') + Decimal('1.05')
Decimal('3.2')
>>> Decimal('1.5').fma(Decimal('1.5'), Decimal('1.05'))
Decimal('3.3')
----------
assignee: docs@python
components: Documentation
messages: 218592
nosy: docs@python, jayanthkoushik
priority: normal
severity: normal
status: open
title: fma documentation should provide better example.
type: enhancement
versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue21510>
_______________________________________
New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>:
I think it would be helpful if the Python documentation included certain high-level information about multi-threading in Python.
At minimum, I think it would help for the documentation to provide a definition that can be linked to of what it means when some part of the Python documentation says something is "thread-safe". In particular, such a definition could clarify that this is different from being atomic. This might best be addressed by an entry in the glossary for the term "thread-safe".
Other documentation possibilities include stating what guarantees one should or should not expect regarding thread-safety, both within and across implementations, and providing centralized guidance on how to approach multi-threaded programming in Python. A HOWTO is one possibility for addressing these other possibilities.
This issue stems from the discussion in issue 15329, which is more specific.
----------
assignee: docs@python
components: Documentation
messages: 165336
nosy: cjerdonek, docs@python
priority: normal
severity: normal
status: open
title: document the threading "facts of life" in Python
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue15339>
_______________________________________
New submission from R. David Murray <rdmurray(a)bitdance.com>:
A common problem encountered when using python3 is writing non-ascii to stdout. This will work fine if stdout is a terminal and the terminal encoding handles the characters, but will fail if stdout is later redirected to a pipe. The docs for sys.stdout and for print should contain or point to an explanation of why, and how to solve the problem (ie: how to set the encoding for sys.stdout/sys.stderr).
Note that IMO it makes more sense for sys.stdout to default to the LOCALE encoding, but that should be a separate issue.
----------
assignee: docs@python
components: Documentation
messages: 142880
nosy: docs@python, r.david.murray
priority: normal
severity: normal
status: open
title: The documentation for the print function should explain/point to how to control the sys.stdout encoding
versions: Python 2.7, Python 3.2, Python 3.3
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue12832>
_______________________________________
New submission from JJeffries <jamesjeffries1(a)gmail.com>:
It is unclear without reference to the logging module where the multiprocessing logging levels fit in the normal logging provided by the logging module, even though it says above the table
"The table below illustrates where theses fit in the
normal level hierarchy.
+----------------+----------------+
| Level | Numeric value |
+================+================+
| ``SUBWARNING`` | 25 |
+----------------+----------------+
| ``SUBDEBUG`` | 5 |
+----------------+----------------+"
I propose adding further values from the logging module for clarification.
----------
assignee: docs@python
components: Documentation
messages: 136839
nosy: JJeffries, docs@python
priority: normal
severity: normal
status: open
title: Multiprocessing logging levels unclear
versions: Python 3.3
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue12174>
_______________________________________
New submission from Arfrever Frehtes Taifersar Arahesis <Arfrever.FTA(a)GMail.Com>:
It's undocumented that imp.find_module("") and imp.find_module(".") try to find __init__.py.
There is also a small difference in behavior between them.
sys.path by default contains "" as the first element, which is sufficient for imp.find_module("."), but not for imp.find_module(""):
$ mkdir /tmp/imp_tests
$ cd /tmp/imp_tests
$ touch __init__.py
$ python3.3 -c 'import imp, sys; print(repr(sys.path[0])); print(imp.find_module("."))'
''
(None, '.', ('', '', 5))
$ python3.3 -c 'import imp, sys; print(repr(sys.path[0])); print(imp.find_module(""))'
''
Traceback (most recent call last):
File "<string>", line 1, in <module>
ImportError: No module named ''
If sys.path contains path (e.g. "." or absolute path) to directory with __init__.py file, then imp.find_module("") will succeed:
$ PYTHONPATH="." python3.3 -c 'import imp, sys; print(repr(sys.path[0:2])); print(imp.find_module("."))'
['', '/tmp/imp_tests']
(None, '.', ('', '', 5))
$ PYTHONPATH="." python3.3 -c 'import imp, sys; print(repr(sys.path[0:2])); print(imp.find_module(""))'
['', '/tmp/imp_tests']
(None, '/tmp/imp_tests/', ('', '', 5))
$ python3.3 -c 'import imp, sys; sys.path.insert(1, "."); print(repr(sys.path[0:2])); print(imp.find_module("."))'
['', '.']
(None, '.', ('', '', 5))
$ python3.3 -c 'import imp, sys; sys.path.insert(1, "."); print(repr(sys.path[0:2])); print(imp.find_module(""))'
['', '.']
(None, './', ('', '', 5))
I think that imp.find_module(".") and imp.find_module("") should have the same behavior, and this behavior should be documented.
----------
assignee: docs@python
components: Documentation, Interpreter Core
messages: 144531
nosy: Arfrever, docs@python
priority: normal
severity: normal
status: open
title: imp.find_module("") and imp.find_module(".")
versions: Python 2.7, Python 3.2, Python 3.3
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue13047>
_______________________________________
New submission from anatoly techtonik <techtonik(a)gmail.com>:
http://docs.python.org/library/pdb.html#pdb.Pdb
Documentation for pdb says: "The debugger is extensible — it is actually defined as the class Pdb. This is currently undocumented but easily understood by reading the source."
There should a link to the source.
----------
assignee: docs@python
components: Documentation, Library (Lib)
messages: 162074
nosy: docs@python, techtonik
priority: normal
severity: normal
status: open
title: pdb: Link to source
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue14979>
_______________________________________
New submission from mpb:
types.NoneType seems to have disappeared in Python 3. This is probably intentional, but I cannot figure out how to test if a variable is of type NoneType in Python 3.
Specifically, I want to write:
assert type (v) in ( bytes, types.NoneType )
Yes, I could write:
assert v is None or type (v) is bytes
But the first assert statement is easier to read (IMO).
Here are links to various Python 3 documentation about None:
[1] http://docs.python.org/3/library/stdtypes.html#index-2
[2] http://docs.python.org/3/library/constants.html#None
Link [2] says: "None The sole value of the type NoneType." However, NoneType is not listed in the Python 3 documentation index. (As compared with the Python 2 index, where NoneType is listed.)
[3] http://docs.python.org/3/library/types.html
If NoneType is gone in Python 3, mention of NoneType should probably be removed from link [2]. If NoneType is present in Python 3, the docs (presumably at least one of the above links, and hopefully also the index) should tell me how to use it.
Here is another link:
[4] http://docs.python.org/3/library/stdtypes.html#bltin-type-objects
"The standard module types defines names for all standard built-in types." (Except <class 'NoneType'> ???)
None is a built-in constant. It has a type. If None's type is not considered to be a "standard built-in type", then IMO this is surprising(!!) and should be documented somewhere (for example, at link [4], and possibly elsewhere as well.)
Thanks!
----------
assignee: docs@python
components: Documentation
messages: 201666
nosy: docs@python, mpb
priority: normal
severity: normal
status: open
title: Where is NoneType in Python 3?
versions: Python 3.3
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue19438>
_______________________________________
New submission from Serhiy Storchaka:
Some documentation files contain a number of I/my/me. Looks like they grew from personal modules and personal articles. Perhaps the official documentation needs more depersonalized style. Here is full list of such files:
Doc/c-api/exceptions.rst
Doc/c-api/long.rst
Doc/distutils/builtdist.rst
Doc/extending/extending.rst
Doc/extending/windows.rst
Doc/howto/argparse.rst
Doc/howto/curses.rst
Doc/howto/functional.rst
Doc/howto/regex.rst
Doc/howto/sockets.rst
Doc/howto/urllib2.rst
Doc/install/index.rst
Doc/library/audioop.rst
Doc/library/ctypes.rst
Doc/library/doctest.rst
Doc/library/heapq.rst
Doc/library/numbers.rst
Doc/library/ossaudiodev.rst
Doc/library/tk.rst
Doc/library/unittest.mock-examples.rst
Doc/library/unittest.mock.rst
Doc/reference/introduction.rst
Doc/tutorial/classes.rst
The list doesn't include FAQs where it may be appropriate and whatsnew files.
Andrew Kuchling recently has fixed Doc/howto/unicode.rst for this issue (as part of issue4153).
----------
assignee: docs@python
components: Documentation
messages: 191636
nosy: akuchling, docs@python, eric.araujo, ezio.melotti, georg.brandl, serhiy.storchaka
priority: normal
severity: normal
status: open
title: Documentation is too personalized
versions: Python 2.7, Python 3.3, Python 3.4
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue18280>
_______________________________________