Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Inherited docstrings for pathlib classes are confusing #76153

Closed
merwok opened this issue Nov 7, 2017 · 5 comments
Closed

Inherited docstrings for pathlib classes are confusing #76153

merwok opened this issue Nov 7, 2017 · 5 comments
Assignees
@merwok
Labels
3.7 (EOL) end of life 3.8 only security fixes docs Documentation in the Doc dir easy stdlib Python modules in the Lib dir type-feature A feature request or enhancement

Comments

@merwok
Copy link
Member

merwok commented Nov 7, 2017

BPO 31972
Nosy @pitrou, @merwok, @chason, @miss-islington
PRs
  • bpo-31972: Improve docstrings for pathlib classes #5310
  • [3.6] bpo-31972: Improve docstrings for pathlib classes (GH-5310) #5749
  • [3.7] bpo-31972: Improve docstrings for pathlib classes (GH-5310) #5750
    		•

    Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = 'https://github.com/merwok'
closed_at = <Date 2018-02-19.01:00:42.515>
created_at = <Date 2017-11-07.19:05:43.171>
labels = ['easy', 'type-feature', '3.8', '3.7', 'library', 'docs']
title = 'Inherited docstrings for pathlib classes are confusing'
updated_at = <Date 2018-02-19.01:01:16.857>
user = 'https://github.com/merwok'

    bugs.python.org fields:

    activity = <Date 2018-02-19.01:01:16.857>
actor = 'eric.araujo'
assignee = 'eric.araujo'
closed = True
closed_date = <Date 2018-02-19.01:00:42.515>
closer = 'eric.araujo'
components = ['Documentation', 'Library (Lib)']
creation = <Date 2017-11-07.19:05:43.171>
creator = 'eric.araujo'
dependencies = []
files = []
hgrepos = []
issue_num = 31972
keywords = ['patch', 'easy']
message_count = 5.0
messages = ['305788', '312332', '312334', '312335', '312336']
nosy_count = 5.0
nosy_names = ['pitrou', 'eric.araujo', 'docs@python', 'chason.chaffin', 'miss-islington']
pr_nums = ['5310', '5749', '5750']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue31972'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8']
    @merwok
    Copy link
    Member Author

    merwok commented Nov 7, 2017

    pydoc pathlib.Path shows the docstring of PurePath:

    | PurePath represents a filesystem path and offers operations which
    | don't imply any actual filesystem I/O.

    But immediately after we see methods like chmod, exists and co which obviously aren’t pure. Looking at the reST docs or the source code, the reader can deduce that this is the docstring of PurePath inherited by Path, but I find it confusing.

    Solution: adding docstrings to all pathlib classes. PurePath and Path can have all the info, Posix/Windows* subclasses only one line with a reference.

    @merwok merwok added 3.7 (EOL) end of life stdlib Python modules in the Lib dir easy type-feature A feature request or enhancement labels Nov 7, 2017
    @serhiy-storchaka serhiy-storchaka added the docs Documentation in the Doc dir label Nov 8, 2017
    @merwok
    Copy link
    Member Author

    merwok commented Feb 18, 2018

    New changeset dfa015c by Éric Araujo (chason) in branch 'master':
    bpo-31972: Improve docstrings for pathlib classes (bpo-5310)
    dfa015c

    @miss-islington
    Copy link
    Contributor

    New changeset 5c81ed4 by Miss Islington (bot) in branch '3.6':
    bpo-31972: Improve docstrings for pathlib classes (GH-5310)
    5c81ed4

    @miss-islington
    Copy link
    Contributor

    New changeset 19b7f66 by Miss Islington (bot) in branch '3.7':
    bpo-31972: Improve docstrings for pathlib classes (GH-5310)
    19b7f66

    @merwok merwok added the 3.8 only security fixes label Feb 19, 2018
    @merwok merwok closed this as completed Feb 19, 2018
    @merwok merwok assigned merwok and unassigned docspython Feb 19, 2018
    @merwok
    Copy link
    Member Author

    merwok commented Feb 19, 2018

    Thanks for the patch!

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees

    @merwok merwok

    Labels
    3.7 (EOL) end of life 3.8 only security fixes docs Documentation in the Doc dir easy stdlib Python modules in the Lib dir type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    3 participants
    @merwok @serhiy-storchaka @miss-islington