From ef85119618e7ba7717a36172675a7d4d5aef4954 Mon Sep 17 00:00:00 2001 From: Antoine Pitrou Date: Tue, 25 Feb 2014 20:33:02 +0100 Subject: Issue #20765: Add missing documentation for PurePath.with_name() and PurePath.with_suffix(). --- Doc/library/pathlib.rst | 30 ++++++++++++++++++++++++++++++ Misc/NEWS | 6 ++++++ 2 files changed, 36 insertions(+) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 3aa9d4b..ec1dc4f 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -522,6 +522,36 @@ Pure paths provide the following methods and properties: ValueError: '/etc/passwd' does not start with '/usr' +.. method:: PurePath.with_name(name) + + Return a new path with the :attr:`name` changed. If the original path + doesn't have a name, ValueError is raised:: + + >>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz') + >>> p.with_name('setup.py') + PureWindowsPath('c:/Downloads/setup.py') + >>> p = PureWindowsPath('c:/') + >>> p.with_name('setup.py') + Traceback (most recent call last): + File "", line 1, in + File "/home/antoine/cpython/default/Lib/pathlib.py", line 751, in with_name + raise ValueError("%r has an empty name" % (self,)) + ValueError: PureWindowsPath('c:/') has an empty name + + +.. method:: PurePath.with_suffix(suffix) + + Return a new path with the :attr:`suffix` changed. If the original path + doesn't have a suffix, the new *suffix* is appended instead:: + + >>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz') + >>> p.with_suffix('.bz2') + PureWindowsPath('c:/Downloads/pathlib.tar.bz2') + >>> p = PureWindowsPath('README') + >>> p.with_suffix('.txt') + PureWindowsPath('README.txt') + + .. _concrete-paths: diff --git a/Misc/NEWS b/Misc/NEWS index 9f9c981..b11cd2e 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -17,6 +17,12 @@ Library - Issue #19748: On AIX, time.mktime() now raises an OverflowError for year outsize range [1902; 2037]. +Documentation +------------- + +- Issue #20765: Add missing documentation for PurePath.with_name() and + PurePath.with_suffix(). + Tests ----- -- cgit v0.12