Skip to content

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

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.

Sign up for GitHub

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

Merged
brettcannon merged 7 commits into from
Jun 2, 2017
Merged

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

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
8102d8e
bpo-24899: Add docs for pathlib.Path.absolute and pathlib to os.path …
slashfoo May 23, 2017
c1475df
bpo-24899: Add note about pathlib.PurePath.relative_to vs os.path.rel…
slashfoo May 23, 2017
3ee0c83
bpo-24899: minor changes to pathlib docs
slashfoo May 25, 2017
6f5b942
bpo-24899: correcting tone, simplify language and deduplicate entries
slashfoo May 26, 2017
955846e
bpo-24899: removing documentation for pathlib.Path.absolute and defer…
slashfoo May 26, 2017
07596a7
bpo-24899: Add Jamiel Almeida to ACKS
slashfoo May 29, 2017
6f24cbd
Re-alphabetize Misc/ACKS
brettcannon Jun 2, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
bpo-24899: minor changes to pathlib docs
  • Loading branch information
@slashfoo
slashfoo committed May 25, 2017
commit 3ee0c83caf5a3b14cb5ed4954e2737248ad4131c
11 changes: 6 additions & 5 deletions Doc/library/pathlib.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -641,8 +641,8 @@ call fails (for example because the path doesn't exist):
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.
Use resolve() to get the canonical path to a file.
No normalization is done, i.e. all ``.`` and ``..`` will be kept along.
Use :meth:`Path.resolve` to get the canonical path to a file.

Usage example::

Expand Down Expand Up @@ -1072,13 +1072,14 @@ call fails (for example because the path doesn't exist):

.. versionadded:: 3.5

Correspondence to tools in the os package
-----------------------------------------
Correspondence to tools in the :mod:`os` package
Copy link
Contributor

@marco-buttu marco-buttu May 25, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@slashfoo slashfoo May 26, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

------------------------------------------------

If you're more familiar with :mod:`os.path` module, here's a correspondence
Copy link
Member

@brettcannon brettcannon May 25, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

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.

Copy link
Contributor Author

@slashfoo slashfoo May 26, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

table on how the same things may be accomplished with pathlib.
table on how the same things may be accomplished with :mod:`pathlib`.

.. note::
Copy link
Contributor

@marco-buttu marco-buttu May 25, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor Author

@slashfoo slashfoo May 25, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


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

@brettcannon brettcannon May 25, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@slashfoo slashfoo May 26, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

adopted the suggested line in next commit.

overlapping use cases, :meth:`PurePath.relative_to` is more oriented towards
answering the question "Relative to a given parent directory, how do I reach
Expand Down