[issue45991] Improve ambiguous docstrings in pkgutil

[Stanley]

Stanley  added the comment:

I feel like there might be some backwards compatibility issues if pkgutil wraps 
it like that, but similarly I'm not at all familiar with how common the package 
is used and whether it'd be fine to make that change, so I'll also differ 
judgement here.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45991] Improve ambiguous docstrings in pkgutil

[Kevin Hock]

Kevin Hock  added the comment:

> Maybe instead a note could be put in the Pathlib doc noting functions that 
> accept path arguments might not accept Path objects?

My concern with that is that someone using `pkgutil` wouldn't see it. However, 
I can see the argument that fixing the 'source' is better than each use. I'm 
not sure how wide-spread these kind of issues are to weigh in on how many 
'uses' there are. If that makes sense.

>Should pkgutil call os.fspath() in this case?

I really like that idea. (I haven't contributed to CPython before, so I'll let 
someone else weigh in on if that is standard practice.)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45991] Improve ambiguous docstrings in pkgutil

[Barney Gale]

Barney Gale  added the comment:

Should pkgutil call os.fspath() in this case?

--
nosy: +barneygale

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45991] Improve ambiguous docstrings in pkgutil

[Stanley]

Stanley  added the comment:

While it is ambiguous, when there's a path parameter I would default it to 
string unless otherwise specified. Maybe instead a note could be put in the 
Pathlib doc noting functions that accept path arguments might not accept Path 
objects?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45991] Improve ambiguous docstrings in pkgutil

[Kevin Hock]

Kevin Hock  added the comment:

At best it is ambiguous, with the class being confused with Str being called 
Path. Looking up "AttributeError: 'PosixPath' object has no attribute 
'startswith'" gives a lot of results for similar issues, so I think the wording 
could be improved.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45991] Improve ambiguous docstrings in pkgutil

[Stanley]

Stanley  added the comment:

Could you expand a bit on why 'list of paths' in pkgutil is understood by 
default to be 'list of PosixPath paths'? I would interpret it by default to be 
string paths if I saw it somewhere without context

--
nosy: +slateny

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45991] Improve ambiguous docstrings in pkgutil

[Irit Katriel]

Change by Irit Katriel :


--
keywords: +easy
versions:  -Python 3.6, Python 3.7, Python 3.8

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45991] Improve ambiguous docstrings in pkgutil

[Kevin Hock]

New submission from Kevin Hock :

# Issue

If you search for "list of paths" in 
https://github.com/KevinHock/cpython/blob/main/Lib/pkgutil.py

A lot of people mistake this as `PosixPath`. You can see an example here: 
https://github.com/duo-labs/parliament/pull/207 that references other OSS 
repositories.

# Solution

We can
- Change the wording. e.g. "list of strings of the paths" or some variation of 
that.

and perhaps additionally

- Throw a ValueError similar to: 
https://github.com/python/cpython/blob/628abe4463ed40cd54ca952a2b4cc2d6e74073f7/Lib/pkgutil.py#L122

--
assignee: docs@python
components: Documentation
messages: 407727
nosy: docs@python, khock
priority: normal
severity: normal
status: open
title: Improve ambiguous docstrings in pkgutil
type: enhancement
versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python 
3.9

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com