New submission from Ram Rachum <ram(a)rachum.com>:
Looking at the enum source code, there's a method `_create_pseudo_member_` that's used in a bunch of places. Its docstring says "Create a composite member iff value contains only members", which would have been useful if I had any idea what "composite member" meant.
It would be good if the documentation for the enum module would include more information about these two concepts.
----------
assignee: docs@python
components: Documentation
messages: 364561
nosy: cool-RR, docs@python
priority: normal
severity: normal
status: open
title: enum: Add documentation for _create_pseudo_member_ and composite members
type: enhancement
versions: Python 3.8, Python 3.9
_______________________________________
Python tracker <report(a)bugs.python.org>
<https://bugs.python.org/issue40006>
_______________________________________
New submission from Andy Maier <andreas.r.maier(a)gmx.de>:
I found that os.path.relpath() on Windows raises ValueError when the path and the start path are on different drives. This is to be expected, as there is no single root on Windows.
On Python 3.7, the behavior is:
>>> os.path.relpath('c:/abc', 'a:/')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "...\Python\Python37\lib\ntpath.py", line 564, in relpath
path_drive, start_drive))
ValueError: path is on mount 'c:', start on mount 'a:'
The issue is that this ValueError and the reasons for it are not mentioned at all in the documentation for os.path.relpath(). Other os.path functions do document specific behaviors for different drives on Windows, for example os.path.commonpath(), so there is a precedence for documenting this. Also, it should be normal to document the possible exceptions that can be raised.
I did read https://bugs.python.org/issue7195 from 2009 where the original issue discussed also lead to a request to update the documentation of os.path.relpath() to show the ValueError for this case, but that angle of the issue ended up being ignored back then, unfortunately.
My suggestion is to add something like the following sentence the documentation:
"On Windows, ValueError is raised when path and start are on different drives."
----------
assignee: docs@python
components: Documentation
messages: 376057
nosy: andymaier, docs@python
priority: normal
severity: normal
status: open
title: os.path.relpath does not document ValueError on Windows with different drives
versions: Python 3.7
_______________________________________
Python tracker <report(a)bugs.python.org>
<https://bugs.python.org/issue41661>
_______________________________________
New submission from igo95862 <igo9586(a)gmail.com>:
This is package documentation: https://docs.python.org/3/tutorial/modules.html#packages
To make package executable (python -m package) you need to create a file __main__.py in the package directory.
This is pretty much not documented anyone aside of trying to run a package missing __main__.py
This page already contains information on how to make module executable. (https://docs.python.org/3/tutorial/modules.html#executing-modules-as-scripts)
----------
assignee: docs@python
components: Documentation
messages: 362790
nosy: docs@python, igo95862
priority: normal
severity: normal
status: open
title: Missing documentation on how to make package executable as script
type: enhancement
versions: Python 3.8
_______________________________________
Python tracker <report(a)bugs.python.org>
<https://bugs.python.org/issue39774>
_______________________________________
New submission from Nguyễn Gia Phong <vn.mcsinyx(a)gmail.com>:
Dear Maintainer,
I want to request a feature on the generative documentation of type-hinting.
As of December 2019, I believe there is no support for generating such
information in help(). For demonstration, I have this tiny piece of code
class Foo:
@property
def bar(self) -> int: return 42
@bar.setter
def bar(self, value: int) -> None: pass
def baz(self, arg: float) -> str: pass
whose documentation on CPython 3.7.5 (on Debian testing amd64 if that matters)
is generated as
class Foo(builtins.object)
| Methods defined here:
|
| baz(self, arg: float) -> str
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
|
| bar
I expect the documentation for bar to be as informative as bar, i.e. something
similar to ``bar: int''. As pointed out by ChrisWarrick on freenode#python,
the annotations are already present, yet help() is not making use of them:
>>> Foo.bar.fget.__annotations__
{'return': <class 'int'>}
>>> Foo.bar.fset.__annotations__
{'value': <class 'int'>, 'return': None}
Have a Merry Christmas or other holiday of your choice,
Nguyễn Gia Phong
----------
assignee: docs@python
components: Documentation
messages: 358823
nosy: McSinyx, docs@python
priority: normal
severity: normal
status: open
title: Type signature of @property not shown in help()
type: enhancement
versions: 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/issue39125>
_______________________________________
New submission from Roman Joost <roman(a)bromeco.de>:
When running a process which changes UID/GID, some of the following processes will run as the user I change to per process.
In order to reproduce (see the attached reproducer):
1. Change the 'USERNAME' to an unprivileged user on your system.
2. Run the reproducer as a user with elevated privileges (e.g. root or some secondary user you have on your system). Mind you, I don't think the user you run as needs elevated privileges, but that's the user I ran as when I observed this behaviour.
3. The reproducer iterates over a list (It stems from a test function which was checking permissions on log files). Observe the print out, which prints the process' GID, UID and secondary groups before we're changing to the users GID, UID and secondary groups.
4. You should observe that at some point the process prints the user information of the user we want to change to not the one which initially started the script.
Example output when running locally as root:
('B', (0, 0, [0]))
('A', (0, 0, [0]))
('C', (0, 0, [0]))
('E', (0, 0, [0]))
('D', (0, 0, [0]))
('F', (1002, 1002, [10, 135, 1000, 1002]))
('H', (1002, 1002, [10, 135, 1000, 1002]))
('I', (1002, 1002, [10, 135, 1000, 1002]))
('J', (1002, 1002, [10, 135, 1000, 1002]))
('G', (1002, 1002, [10, 135, 1000, 1002]))
('K', (1002, 1002, [10, 135, 1000, 1002]))
('L', (1002, 1002, [10, 135, 1000, 1002]))
('M', (1002, 1002, [10, 135, 1000, 1002]))
('N', (1002, 1002, [10, 135, 1000, 1002]))
I would have expected `0` all the way through.
However, if I initialise the Pool with `maxtasksperchild=1` the isolation seems as expected.
I don't know whether this is a bug or I'm foolish to invoke multiprocessing like this. I've run out of time to investigate this further. It's certainly strange behaviour to me and I thought I better report it, since reproducing seems fairly deterministic.
----------
assignee: docs@python
components: Documentation, Library (Lib)
files: reproducer.py
messages: 357773
nosy: docs@python, romanofski
priority: normal
severity: normal
status: open
title: multiprocessing processes seem to "bleed" user information (GID/UID/groups)
type: behavior
versions: Python 3.6, Python 3.7
Added file: https://bugs.python.org/file48753/reproducer.py
_______________________________________
Python tracker <report(a)bugs.python.org>
<https://bugs.python.org/issue38963>
_______________________________________
New submission from Adam Eltawla <bekerpico(a)gmail.com>:
I noticed the parameter name for imghdr.what in the documentation is wrong
Link: https://docs.python.org/3.8/library/imghdr.html?highlight=imghdr
function imghdr.what(filename, h=None)
In reality:
def what(file, h=None):
It is 'file' not 'filename'.
----------
assignee: docs@python
components: Documentation
messages: 373551
nosy: aeltawela, docs@python
priority: normal
severity: normal
status: open
title: The parameter name for imghdr.what in the documentation is wrong
type: enhancement
versions: Python 3.8
_______________________________________
Python tracker <report(a)bugs.python.org>
<https://bugs.python.org/issue41283>
_______________________________________
New submission from Stephen Farris <stephen.farris(a)jhuapl.edu>:
The subprocess docs state: "When using shell=True, the shlex.quote() function can be used to properly escape whitespace and shell metacharacters in strings that are going to be used to construct shell commands." While this is true on Unix, it is not true on Windows. On Windows it is easy to create scenarios where shell injection still exists despite using shlex.quote properly (e.g. subprocess.run(shlex.quote("'&calc '"), shell=True) launches the Windows calculator, which it wouldn't do if shlex.quote was able to prevent shell injection on Windows). While the shlex docs state that shlex is for Unix, the subprocess docs imply that shlex.quote will work on Windows too, possibly leading some developers to erroneously use shlex.quote on Windows to try to prevent shell injection. Recommend: 1) qualifying the above section in the subprocess docs to make it clear that this only works on Unix, and 2) updating the shlex docs with warnings that shlex.quote in particular is not for use on Windows.
----------
assignee: docs@python
components: Documentation
messages: 371140
nosy: Stephen Farris, docs@python
priority: normal
severity: normal
status: open
title: subprocess docs don't qualify the instruction to use shlex.quote by OS
versions: Python 3.8
_______________________________________
Python tracker <report(a)bugs.python.org>
<https://bugs.python.org/issue40932>
_______________________________________
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 George Fischhof <george(a)fischhof.hu>:
Winreg's documentation lacks mentioning required permission at some points
Hi there,
on page
https://docs.python.org/3/library/winreg.html
it is not mentioned in the description of the following functions:
winreg.DeleteKey
winreg.DeleteKeyEx
winreg.DeleteValue
that they require KEY_SET_VALUE when the registry key is opened.
It is mentioned for example at:
winreg.SetValue
with the following text:
The key identified by the key parameter must have been opened with KEY_SET_VALUE access.
BR,
George
----------
assignee: docs@python
components: Documentation
messages: 328034
nosy: docs@python, georgefischhof
priority: normal
severity: normal
status: open
title: Winreg's documentation lacks mentioning required permission at some points
type: enhancement
versions: Python 3.7
_______________________________________
Python tracker <report(a)bugs.python.org>
<https://bugs.python.org/issue35026>
_______________________________________
New submission from Robert <freshbob1337(a)gmail.com>:
https://docs.python.org/3/tutorial/controlflow.html
4.7.8. Function Annotations
[...] "The following example has a positional argument, a keyword argument, and the return value annotated:"
It is not a "positional argument" but an "optional argument".
----------
assignee: docs@python
components: Documentation
messages: 359443
nosy: docs@python, r0b
priority: normal
severity: normal
status: open
title: Mistaken notion in tutorial
type: enhancement
_______________________________________
Python tracker <report(a)bugs.python.org>
<https://bugs.python.org/issue39231>
_______________________________________