Detail the semantics more, following python-ideas questions

This commit is contained in:
Antoine Pitrou 2012-10-06 01:13:30 +02:00
parent ff1f0a2827
commit 47e356c506
1 changed files with 45 additions and 6 deletions

View File

@ -165,10 +165,32 @@ are tied by backwards compatibility to confusing or plain wrong behaviour
(for example, the fact that ``os.path.abspath()`` simplifies ".." path
components without resolving symlinks first).
Also, using classes instead of plain strings helps make system-dependent
behaviours natural. For example, comparing and ordering Windows path
objects is case-insensitive, and path separators are automatically converted
to the platform default.
Comparisons
-----------
Paths of the same flavour are comparable and orderable, whether pure or not::
>>> PurePosixPath('a') == PurePosixPath('b')
False
>>> PurePosixPath('a') < PurePosixPath('b')
True
>>> PurePosixPath('a') == PosixPath('a')
True
Comparing and ordering Windows path objects is case-insensitive::
>>> PureNTPath('a') == PureNTPath('A')
True
Paths of different flavours always compare unequal, and cannot be ordered::
>>> PurePosixPath('a') == PureNTPath('a')
False
>>> PurePosixPath('a') < PureNTPath('a')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: unorderable types: PurePosixPath() < PureNTPath()
Useful notations
@ -222,8 +244,8 @@ First a couple of conventions:
"anchored" is the same as "absolute".
Construction and joining
------------------------
Construction
------------
We will present construction and joining together since they expose
similar semantics.
@ -256,12 +278,29 @@ However, with Windows paths, the drive is retained as necessary::
>>> PureNTPath('c:/foo', 'd:')
PureNTPath('d:')
Also, path separators are normalized to the platform default::
>>> PureNTPath('a/b') == PureNTPath('a\\b')
True
Extraneous path separators and ``"."`` components are eliminated, but not
``".."`` components::
>>> PurePosixPath('a//b/./c/')
PurePosixPath('a/b/c')
>>> PurePosixPath('a/../b')
PurePosixPath('a/../b')
Calling the constructor without any argument creates a path object pointing
to the logical "current directory"::
>>> PurePosixPath()
PurePosixPath('.')
Joining
-------
A path can be joined with another using the ``__getitem__`` operator::
>>> p = PurePosixPath('foo')