bpo-24899: Add docs for pathlib.Path.absolute and pathlib to os.path correspondence #1753

slashfoo · 2017-05-23T05:36:20Z

Documentation changes for pathlib to have a map for people that are more familiar with os.path.

Briefly discussed with @brettcannon and @gpshead

…correspondence

…path

mention-bot · 2017-05-23T05:36:21Z

@slashfoo, thanks for your PR! By analyzing the history of the files in this pull request, we identified @eliben, @serhiy-storchaka and @marco-buttu to be potential reviewers.

the-knights-who-say-ni · 2017-05-23T05:36:22Z

Hello, and thanks for your contribution!

I'm a bot set up to make sure that the project can legally accept your contribution by verifying you have signed the PSF contributor agreement (CLA).

Unfortunately we couldn't find an account corresponding to your GitHub username on bugs.python.org (b.p.o) to verify you have signed the CLA (this might be simply due to a missing "GitHub Name" entry in your b.p.o account settings). This is necessary for legal reasons before we can look at your contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.

Thanks again to your contribution and we look forward to looking at it!

slashfoo · 2017-05-23T06:27:22Z

signed the CLA.

gpshead · 2017-05-24T01:19:07Z

@bricsuc can you review these doc changes?

marco-buttu · 2017-05-25T06:08:38Z

Doc/library/pathlib.rst

+   Return an absolute version of this path.  This function works
+   even if the path doesn't point to anything.
+
+   No normalization is done, i.e. all '.' and '..' will be kept along.


You should use the code style for '.' and '..'

made the change, thanks for the comment, using double backticks.

marco-buttu · 2017-05-25T06:16:33Z

Doc/library/pathlib.rst

+   even if the path doesn't point to anything.
+
+   No normalization is done, i.e. all '.' and '..' will be kept along.
+   Use resolve() to get the canonical path to a file.


:meth:`Path.resolve`

good catch, changed in next commit.

marco-buttu · 2017-05-25T06:27:15Z

Doc/library/pathlib.rst


   .. versionadded:: 3.5
+
+Correspondence to tools in the os package


:mod:`os` module

changed in next commit.

marco-buttu · 2017-05-25T06:29:40Z

Doc/library/pathlib.rst

+-----------------------------------------
+
+If you're more familiar with :mod:`os.path` module, here's a correspondence
+table on how the same things may be accomplished with pathlib.


:mod:`pathlib`

changed in next commit.

marco-buttu · 2017-05-25T06:35:46Z

Doc/library/pathlib.rst

+If you're more familiar with :mod:`os.path` module, here's a correspondence
+table on how the same things may be accomplished with pathlib.
+
+.. note::


I see in this file there is no blank line after .. note::, but this role does not apply to the rest of the doc. Maybe @brettcannon could tell us what is the policy. Another question: what to do in case the policy is to have a blank line? Do we stay consistent with the file or with the general policy?

I added the blank line, to adhere to general policy, at least with this change.

marco-buttu · 2017-05-25T07:21:24Z

Doc/library/pathlib.rst


-Correspondence to tools in the os package
-----------------------------------------
+Correspondence to tools in the :mod:`os` package


os is a module. You should write: .... tools in the:mod:`os` module

thanks, I missed that correction from last comment, I thought only the link was missing. Fixing in next commit.

brettcannon · 2017-05-25T21:47:04Z

Doc/library/pathlib.rst

 methods.  Many of these methods can raise an :exc:`OSError` if a system
 call fails (for example because the path doesn't exist):

+.. method:: Path.absolute()


Please don't document Path.absolute() until bpo-29688 is resolved.

Should we wait, or pluck it from this pull request?

saw the discussion on the linked issue, and I think it's better to pluck it from this one. Doing that on next commit.

brettcannon · 2017-05-25T21:49:19Z

Doc/library/pathlib.rst

+Correspondence to tools in the :mod:`os` package
+------------------------------------------------
+
+If you're more familiar with :mod:`os.path` module, here's a correspondence


Below is a table mapping various :mod:`os` functions to their corresponding :class:`PurePath`/:class:`Path` equivalent.

Basically the documentation doesn't take quite such a casual, conversational tone.

Thanks for the correction, changing that line to the suggested one.

brettcannon · 2017-05-25T21:52:30Z

Doc/library/pathlib.rst

+
+.. note::
+
+   Although :func:`os.path.relpath` and :meth:`PurePath.relative_to` have some


I would simplify this note to:

Although :func:`os.path.relpath` and :meth:`PurePath.relative_to` have some overlapping use-cases, their semantics differ enough to warrant not considering them equivalent.

If people want to dive deeper they can then read the docs for the two functions.

adopted the suggested line in next commit.

brettcannon · 2017-05-25T21:53:49Z

Doc/library/pathlib.rst

+============================   ==============================
+os and os.path                 pathlib
+============================   ==============================
+:func:`os.path.abspath`        :func:`Path.absolute`


Should probably change this to Path.resolve.

changed Path.absolute to Path.resolve

brettcannon · 2017-05-25T21:54:05Z

Doc/library/pathlib.rst

+============================   ==============================
+:func:`os.path.abspath`        :func:`Path.absolute`
+:func:`os.getcwd`              :func:`Path.cwd`
+:func:`os.path.abspath`        :meth:`Path.absolute`


Duplicate line.

removed duplicate.

brettcannon · 2017-05-25T21:55:29Z

Doc/library/pathlib.rst

+:func:`os.path.isfile`         :meth:`Path.is_file`
+:func:`os.path.islink`         :meth:`Path.is_symlink`
+:func:`os.stat`                :meth:`Path.owner`
+:func:`os.stat`                :meth:`Path.stat`


I would combine the three os.stat lines into one and simply comma-separate the pathlib equivalents. Otherwise someone looking for an os.stat equivalent will find the first solution and then never see the other two.

makes perfect sense, thanks. collapsed the os.stat lines into one.

…ring to bpo-29688

brettcannon · 2017-05-27T19:52:26Z

What do you think of the latest version, @marco-buttu ?

marco-buttu · 2017-05-28T09:24:10Z

@brettcannon it LGTM :-)

brettcannon · 2017-05-28T19:21:00Z

@slashfoo this chart took enough effort to warrant an ACKS mention if you want to add yourself to the file before I merge this PR.

slashfoo · 2017-05-29T21:48:55Z

Thanks @brettcannon, I did now. I'm happy to be on that list. Now I just need to find more stuff on bpo for me.

slashfoo added 2 commits May 22, 2017 22:27

bpo-24899: Add docs for pathlib.Path.absolute and pathlib to os.path …

8102d8e

…correspondence

bpo-24899: Add note about pathlib.PurePath.relative_to vs os.path.rel…

c1475df

…path

the-knights-who-say-ni added the CLA not signed label May 23, 2017

brettcannon self-requested a review May 23, 2017 17:34

marco-buttu suggested changes May 25, 2017

View reviewed changes

bpo-24899: minor changes to pathlib docs

3ee0c83

the-knights-who-say-ni added CLA signed and removed CLA not signed labels May 25, 2017

marco-buttu suggested changes May 25, 2017

View reviewed changes

brettcannon requested changes May 25, 2017

View reviewed changes

slashfoo added 2 commits May 25, 2017 22:36

bpo-24899: correcting tone, simplify language and deduplicate entries

6f5b942

bpo-24899: removing documentation for pathlib.Path.absolute and defer…

955846e

…ring to bpo-29688

brettcannon approved these changes May 27, 2017

View reviewed changes

marco-buttu approved these changes May 28, 2017

View reviewed changes

brettcannon self-assigned this May 28, 2017

bpo-24899: Add Jamiel Almeida to ACKS

07596a7

Re-alphabetize Misc/ACKS

6f24cbd

brettcannon merged commit ae8750b into python:master Jun 2, 2017


		.. versionadded:: 3.5

		Correspondence to tools in the os package


		.. note::

		Although :func:`os.path.relpath` and :meth:`PurePath.relative_to` have some

Uh oh!

bpo-24899: Add docs for pathlib.Path.absolute and pathlib to os.path correspondence #1753

bpo-24899: Add docs for pathlib.Path.absolute and pathlib to os.path correspondence #1753

Uh oh!

Conversation

slashfoo commented May 23, 2017

Uh oh!

mention-bot commented May 23, 2017

Uh oh!

the-knights-who-say-ni commented May 23, 2017

Uh oh!

slashfoo commented May 23, 2017

Uh oh!

gpshead commented May 24, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

slashfoo May 26, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brettcannon commented May 27, 2017

Uh oh!

marco-buttu commented May 28, 2017

Uh oh!

brettcannon commented May 28, 2017

Uh oh!

slashfoo commented May 29, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

slashfoo May 26, 2017 •

edited

Loading