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: Add note about pathlib.PurePath.relative_to vs os.path.rel… 
…path
  • Loading branch information
@slashfoo
slashfoo committed May 23, 2017
commit c1475df79b6ace9b2d83a9e11d763be8a3b919c9
10 changes: 10 additions & 0 deletions Doc/library/pathlib.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1078,6 +1078,16 @@ Correspondence to tools in the os package
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.
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.

:mod:`pathlib`

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.

changed in next commit.


.. 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
this descendant path?" whereas :func:`os.path.relpath` is implemented to
answer the "How do I get to path A from path B?".

If the parameter passed to :meth:`PurePath.relative_to` is not a parent
node of the object, :exc:`ValueError` exception is raised.

============================ ==============================
os and os.path pathlib
============================ ==============================
Expand Down