Here is a patch integrating pathlib and its docs.
Note that this was already briefly reviewed by Guido.

New patch with a whatsnew entry.

Updated patch addressing review comments.

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.

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

I'm closing this issue. Please make any further comments in new issues!

Antoine, am I missing something - I don't see documentation for the construction of Path/PurePath?

> 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

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.

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.

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]

> 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 :-)

>
>
> 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.

> > > 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.

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.