classification
Title: PEP 428 implementation
Type: enhancement Stage: resolved
Components: Library (Lib) Versions: Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: eli.bendersky, larry, neologix, pitrou, python-dev
Priority: release blocker Keywords: patch

Created on 2013-11-20 22:20 by pitrou, last changed 2013-11-24 23:24 by eli.bendersky. This issue is now closed.

Files
File name Uploaded Description Edit
pathlib.patch pitrou, 2013-11-20 22:20 review
pathlib2.patch pitrou, 2013-11-21 01:08 review
pathlib3.patch pitrou, 2013-11-22 16:09 review
Messages (15)
msg203540 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-11-20 22:20
Here is a patch integrating pathlib and its docs.
Note that this was already briefly reviewed by Guido.
msg203553 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-11-21 01:08
New patch with a whatsnew entry.
msg203791 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-11-22 15:57
Updated patch addressing review comments.
msg203794 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-11-22 16:10
I plan to commit soon, if there are no further comments.
Remember the pathlib API is provisional, so API changes can still be made later if deemed necessary.
msg203803 - (view) Author: Roundup Robot (python-dev) Date: 2013-11-22 16:38
New changeset 43377dcfb801 by Antoine Pitrou in branch 'default':
Issue #19673: Add pathlib to the stdlib as a provisional module (PEP 428).
http://hg.python.org/cpython/rev/43377dcfb801
msg203806 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-11-22 16:48
I'm closing this issue. Please make any further comments in new issues!
msg204249 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2013-11-24 18:13
Antoine, am I missing something - I don't see documentation for the construction of Path/PurePath?
msg204250 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-11-24 18:19
> Antoine, am I missing something - I don't see documentation for the construction of Path/PurePath?

It's there:
http://docs.python.org/dev/library/pathlib.html#pathlib.PurePath
msg204251 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2013-11-24 18:21
Yes, I've seen that. What I mean is that there's no clear signature defined with each argument explained, as the other stdlib documentation usually does. Section 11.1.2.1 uses a more descriptive approach, while I was also expecting a formal specification.

I can propose a patch to improve this, if you don't object.
msg204252 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-11-24 18:23
Well, it depends how much "formal" :-)

The text does say: """Path constructors accept an arbitrary number of positional arguments. When called without any argument, a path object points to the current directory [etc.]"""

I'm not against a more formal description, but besides saying "*args", I'm not sure what it would bring.
msg204255 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2013-11-24 18:39
It's just a matter of looking for a familiar pattern while going over an unfamiliar doc page, I guess. I'll give it a try and see if it helps.

Another question: What is the real purpose of pure paths? One thing I see is using them to, say, manipulate Windows paths on a Posix machine for some reason. Any others? Could this also be achieved with just having Paths?

[sorry for coming long after the party ended; my motivation here is mainly curiosity - maybe by looking at it from a newbie point of view I can improve the documentation in a way that will be friendlier for people unfamiliar with the new library]
msg204256 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-11-24 18:55
> Another question: What is the real purpose of pure paths? One thing I
> see is using them to, say, manipulate Windows paths on a Posix machine
> for some reason.

Yes. Also, if some reason you want to be sure you're only doing path
computations, not I/O.

> Any others? Could this also be achieved with just having Paths?

I don't see how having just Paths would achieve this, unless you think
it's sane to pretend to walk a Windows directory under Unix :-)
msg204278 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2013-11-24 22:43
>
>
> Antoine Pitrou added the comment:
>
> > Another question: What is the real purpose of pure paths? One thing I
> > see is using them to, say, manipulate Windows paths on a Posix machine
> > for some reason.
>
> Yes. Also, if some reason you want to be sure you're only doing path
> computations, not I/O.
>

"Sure" in what sense, like accidentally? IIUC path manipulation/computation
operations don't really call into the OS - only some methods do.

> > Any others? Could this also be achieved with just having Paths?
>
> I don't see how having just Paths would achieve this, unless you think
> it's sane to pretend to walk a Windows directory under Unix :-)
>

I mean, having Path, WindowsPath and PosixPath without the pure
counterparts. You usually use Path, but say you want to manipulate Windows
paths on a Linux box. So you instantiate a WindowsPath explicitly and do
your thing on it. You can't (NotImplementedError) call any methods that
would call into the OS, and that's it.

I'm just trying to look at the module from the POV of someone who sees it
for the first time, wondering "why do I have two kinds of things here, and
when would I want to use each? could I just use Path 99.9% of the time and
forget about the other options?". If that's true, we may want to reflect it
in the documentation explicitly - I believe this will make the module
easier to understand.
msg204280 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-11-24 22:54
> > > Another question: What is the real purpose of pure paths? One thing I
> > > see is using them to, say, manipulate Windows paths on a Posix machine
> > > for some reason.
> >
> > Yes. Also, if some reason you want to be sure you're only doing path
> > computations, not I/O.
> >
> 
> "Sure" in what sense, like accidentally? IIUC path
> manipulation/computation operations don't really call into the OS -
> only some methods do.

Yes, I was including the methods inside "computations".

> I mean, having Path, WindowsPath and PosixPath without the pure
> counterparts. You usually use Path, but say you want to manipulate Windows
> paths on a Linux box. So you instantiate a WindowsPath explicitly and do
> your thing on it. You can't (NotImplementedError) call any methods that
> would call into the OS, and that's it.

That would have been a possibility, but I find having distinct classes
much cleaner than raising NotImplementedError in many places.  It's also
self-documenting about which operations are "pure" and which operations
are not.

> I'm just trying to look at the module from the POV of someone who sees it
> for the first time, wondering "why do I have two kinds of things here, and
> when would I want to use each? could I just use Path 99.9% of the time and
> forget about the other options?". If that's true, we may want to reflect it
> in the documentation explicitly - I believe this will make the module
> easier to understand.

Well, at the beginning of the doc there's: """The main point of entry is
the Path class, which will instantiate a concrete path for the current
platform.""", and the "basic use" section only uses the Path class.
msg204283 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2013-11-24 23:24
Thanks for the clarifications, Antoine. I'll see if I can come up with a doc patch that will try to emphasize these points. I'll probably just open a new, doc-issue to stop overloading this one.
History
Date User Action Args
2013-11-24 23:24:45eli.benderskysetmessages: + msg204283
2013-11-24 22:54:13pitrousetmessages: + msg204280
2013-11-24 22:43:49eli.benderskysetmessages: + msg204278
2013-11-24 18:55:57pitrousetmessages: + msg204256
2013-11-24 18:39:42eli.benderskysetmessages: + msg204255
2013-11-24 18:23:28pitrousetmessages: + msg204252
2013-11-24 18:21:36eli.benderskysetmessages: + msg204251
2013-11-24 18:19:40pitrousetmessages: + msg204250
2013-11-24 18:13:16eli.benderskysetnosy: + eli.bendersky
messages: + msg204249
2013-11-22 16:48:03pitrousetstatus: open -> closed
resolution: fixed
messages: + msg203806

stage: patch review -> resolved
2013-11-22 16:38:50python-devsetnosy: + python-dev
messages: + msg203803
2013-11-22 16:10:23pitrousetmessages: + msg203794
2013-11-22 16:09:20pitrousetfiles: + pathlib3.patch
2013-11-22 16:09:09pitrousetfiles: - pathlib3.patch
2013-11-22 15:57:41pitrousetfiles: + pathlib3.patch
2013-11-22 15:57:15pitrousetnosy: + neologix
messages: + msg203791
2013-11-21 01:08:02pitrousetfiles: + pathlib2.patch

messages: + msg203553
2013-11-20 22:20:45pitroucreate