summaryrefslogtreecommitdiffstats
path: root/Doc/library/pathlib.rst
Commit message (Collapse)AuthorAgeFilesLines
* [3.13] gh-133286: add explanation about `seq` for pathlib Pattern Language ↵Miss Islington (bot)2025-05-161-2/+5
| | | | | | | | (GH-133340) (#134106) gh-133286: add explanation about `seq` for pathlib Pattern Language (GH-133340) (cherry picked from commit ac8df4b5892d2e4bd99731e7d87223a35c238f81) Co-authored-by: alexey semenyuk <alexsemenyuk88@gmail.com>
* [3.13] gh-123517: Remove unnecessary `:meth:` parentheses (gh-123518) ↵Wei-Hsiang (Matt) Wang2024-09-021-5/+5
| | | | (GH-123577)
* [3.13] GH-120794: Use example paths with multiple parts in pathlib docs ↵Miss Islington (bot)2024-08-101-8/+8
| | | | | | | | | | | | | (GH-122887) (#122895) GH-120794: Use example paths with multiple parts in pathlib docs (GH-122887) In the documentation of `PosixPath` and `WindowsPath`, and their `Pure*` equivalents, use example paths with multiple non-anchor parts. (cherry picked from commit 363374cf69a7e2292fe3f1c6bedd199088958cc2) Co-authored-by: Barney Gale <barney.gale@gmail.com> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
* [3.13] GH-121462: pathlib docs: improve table of corresponding os/os.path ↵Miss Islington (bot)2024-07-271-36/+51
| | | | | | | | | | | | | | | | | | | | | | | functions (GH-121465) (#122359) Re-order table of corresponding functions with the following priorities: 1. Pure functionality is at the top 2. `os.path` functions are shown before `os` functions 3. Similar functionality is kept together 4. Functionality follows docs order where possible Add a few missed correspondences: - `os.path.isjunction` and `Path.is_junction` - `os.path.ismount` and `Path.is_mount` - `os.lstat()` and `Path.lstat()` - `os.lchmod()` and `Path.lchmod()` Also add footnotes describing a few differences. (cherry picked from commit cbac8a3888411587beb026e246889154fbdd49a3) Co-authored-by: Barney Gale <barney.gale@gmail.com>
* [3.13] Docs: spelling and grammar fixes (GH-122084) (#122106)Miss Islington (bot)2024-07-221-1/+1
| | | | | | | | | | | Docs: spelling and grammar fixes (GH-122084) Corrected some grammar and spelling issues in documentation. (cherry picked from commit bc264eac3ad14dab748e33b3d714c2674872791f) Co-authored-by: Ville Skyttä <ville.skytta@iki.fi> Co-authored-by: Russell Keith-Magee <russell@keith-magee.com> Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
* [3.13] GH-119054: Add alt text to pathlib inheritance diagram (GH-121158) ↵Miss Islington (bot)2024-06-291-0/+6
| | | | | | | | | (#121168) GH-119054: Add alt text to pathlib inheritance diagram (GH-121158) (cherry picked from commit 6b280a84988ca221b5bdc1077a914e873790cce5) Co-authored-by: Barney Gale <barney.gale@gmail.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
* [3.13] GH-119054: Add "Expanding and resolving paths" section to pathlib ↵Miss Islington (bot)2024-06-291-101/+101
| | | | | | | | | | | | | | | | | | | | | | | | docs. (GH-120970) (#121155) GH-119054: Add "Expanding and resolving paths" section to pathlib docs. (GH-120970) Add dedicated subsection for `home()`, `expanduser()`, `cwd()`, `absolute()`, `resolve()` and `readlink()`. The position of this section keeps all the `Path` constructors (`Path()`, `Path.from_uri()`, `Path.home()` and `Path.cwd()`) near the top. Within the section, closely related methods are kept adjacent. Specifically: - `home()` and `expanduser()` (the former calls the latter) - `cwd()` and `absolute()` (the former calls the latter) - `absolute()` and `resolve()` (both make paths absolute) - `resolve()` and `readlink()` (both read symlink targets) - Ditto `cwd()` and `absolute()` - Ditto `absolute()` and `resolve()` The "Other methods" section is removed. (cherry picked from commit d6d8707ff217f211f3a2e48084cc0ddfa41efc4d) Co-authored-by: Barney Gale <barney.gale@gmail.com>
* [3.13] GH-119054: Add "Permissions and ownership" section to pathlib docs. ↵Barney Gale2024-06-241-48/+51
| | | | | | | | (GH-120505) (#120967) Add dedicated subsection for `pathlib.owner()`, `group()`, `chmod()` and `lchmod()`. (cherry picked from commit e4a97a7fb1c03d3b6ec6efbeff553a0230e003c7)
* [3.13] GH-119054: Add "Renaming and deleting" section to pathlib docs. ↵Miss Islington (bot)2024-06-131-60/+64
| | | | | | | | | | | (GH-120465) (#120472) GH-119054: Add "Renaming and deleting" section to pathlib docs. (GH-120465) Add dedicated subsection for `pathlib.Path.rename()`, `replace()`, `unlink()` and `rmdir()`. (cherry picked from commit d88a1f2e156cd1072119afa91d4f4dc4037c1b21) Co-authored-by: Barney Gale <barney.gale@gmail.com>
* [3.13] GH-119054: Add "Creating files and directories" section to pathlib ↵Miss Islington (bot)2024-06-131-79/+86
| | | | | | | | | | | | | | docs. (GH-120186) (#120462) GH-119054: Add "Creating files and directories" section to pathlib docs. (GH-120186) Add dedicated subsection for `pathlib.Path.touch()`, `mkdir()`, `symlink_to()` and `hardlink_to()`. Also note that `open()`, `write_text()` and `write_bytes()` are often used to create files. (cherry picked from commit c2d810b6d4deeea530648a8d0983e3a2adf6c942) Co-authored-by: Barney Gale <barney.gale@gmail.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
* [3.13] GH-119054: Add "Reading directories" section to pathlib docs ↵Barney Gale2024-06-071-96/+103
| | | | | | | | | | (GH-119956) (#120183) Add a dedicated subsection for `Path.iterdir()`-related methods, specifically `iterdir()`, `glob()`, `rglob()` and `walk()`. (cherry picked from commit 14e1506a6d7056c38fbbc0797268dcf783f91243) Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
* [3.13] GH-119054: Add "Reading and writing files" section to pathlib docs ↵Miss Islington (bot)2024-06-021-79/+84
| | | | | | | | | | (GH-119524) (#119954) Add a dedicated subsection for `open()`, `read_text()`, `read_bytes()`, `write_text()` and `write_bytes()`. (cherry picked from commit bd6d4ed6454378e48dab06f50a9be0bae6baa3a2) Co-authored-by: Barney Gale <barney.gale@gmail.com>
* [3.13] GH-119054: Add "Querying file type and status" section to pathlib ↵Barney Gale2024-06-021-173/+178
| | | | | | | | docs (GH-119055) (#119951) Add a dedicated subsection for `Path.stat()`-related methods, specifically `stat()`, `lstat()`, `exists()`, `is_*()`, and `samefile()`. (cherry picked from commit 81d63362302187e5cb838c9a7cd857181142e530)
* [3.13] Format None, True, False and NotImplemented as literals (GH-118758) ↵Miss Islington (bot)2024-05-081-2/+2
| | | | | | | (GH-118792) (cherry picked from commit 05c2fe1acda9ea5a57061642c36e8b73bb4fbba4) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
* [3.13] docs: module page titles should not start with a link to themselves ↵Miss Islington (bot)2024-05-081-3/+2
| | | | | | | | (GH-117099) (#118790) docs: module page titles should not start with a link to themselves (GH-117099) (cherry picked from commit bcb435ee8ff41b5ec5d879ee0b6651f146a66151) Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
* GH-115060: Speed up `pathlib.Path.glob()` by omitting initial `stat()` (#117831)Barney Gale2024-04-131-4/+5
| | | | | | | | Since 6258844c, paths that might not exist can be fed into pathlib's globbing implementation, which will call `os.scandir()` / `os.lstat()` only when strictly necessary. This allows us to drop an initial `self.is_dir()` call, which saves a `stat()`. Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
* GH-77609: Add recurse_symlinks argument to `pathlib.Path.glob()` (#117311)Barney Gale2024-04-051-13/+8
| | | | | | | | | | | | | | | Replace tri-state `follow_symlinks` with boolean `recurse_symlinks` argument. The new argument controls whether symlinks are followed when expanding recursive `**` wildcards. The possible argument values correspond as follows: follow_symlinks recurse_symlinks =============== ================ False N/A None False True True We therefore drop support for not following symlinks when expanding non-recursive pattern parts; it wasn't requested in the original issue, and it's a feature not found in any shells. This makes the API a easier to grok by eliminating `None` as an option. No news blurb as `follow_symlinks` was new in 3.13.
* GH-114575: Rename `PurePath.pathmod` to `PurePath.parser` (#116513)Barney Gale2024-03-311-2/+2
| | | And rename the private base class from `PathModuleBase` to `ParserBase`.
* GH-106747: Document another difference between `glob` and `pathlib`. (#116518)Barney Gale2024-03-221-0/+4
| | | | | Document that `path.glob()` might return *path*, whereas `glob.glob(root_dir=path)` will never return an empty string corresponding to *path*.
* GH-113838: Add "Comparison to os.path" section to pathlib docs (#115926)Barney Gale2024-03-151-19/+44
|
* Docs: fix broken links (#116651)Mariusz Felisiak2024-03-131-1/+1
|
* GH-101112: Add "pattern language" section to pathlib docs (#114030)Barney Gale2024-02-261-56/+103
| | | Explain the `full_match()` / `glob()` / `rglob()` pattern language in its own section. Move `rglob()` documentation under `glob()` and reduce duplicated text.
* GH-70303: Make `pathlib.Path.glob('**')` return both files and directories ↵Barney Gale2024-01-301-3/+2
| | | | | | | | | | | | (#114684) Return files and directories from `pathlib.Path.glob()` if the pattern ends with `**`. This is more compatible with `PurePath.full_match()` and with other glob implementations such as bash and `glob.glob()`. Users can add a trailing slash to match only directories. In my previous patch I added a `FutureWarning` with the intention of fixing this in Python 3.15. Upon further reflection I think this was an unnecessarily cautious remedy to a clear bug.
* gh-88569: add `ntpath.isreserved()` (#95486)Barney Gale2024-01-261-7/+6
| | | | | | | | | | | Add `ntpath.isreserved()`, which identifies reserved pathnames such as "NUL", "AUX" and "CON". Deprecate `pathlib.PurePath.is_reserved()`. --------- Co-authored-by: Eryk Sun <eryksun@gmail.com> Co-authored-by: Brett Cannon <brett@python.org> Co-authored-by: Steve Dower <steve.dower@microsoft.com>
* GH-73435: Add `pathlib.PurePath.full_match()` (#114350)Barney Gale2024-01-261-30/+30
| | | | | | | | | | | | | | | | In 49f90ba we added support for the recursive wildcard `**` in `pathlib.PurePath.match()`. This should allow arbitrary prefix and suffix matching, like `p.match('foo/**')` or `p.match('**/foo')`, but there's a problem: for relative patterns only, `match()` implicitly inserts a `**` token on the left hand side, causing all patterns to match from the right. As a result, it's impossible to match relative patterns from the left: `PurePath('foo/bar').match('bar/**')` is true! This commit reverts the changes to `match()`, and instead adds a new `full_match()` method that: - Allows empty patterns - Supports the recursive wildcard `**` - Matches the *entire* path when given a relative pattern
* GH-105900: Fix `pathlib.Path.symlink_to(target_is_directory=...)` docs (#114035)Barney Gale2024-01-231-3/+7
| | | | Clarify that *target_is_directory* only matters if the target doesn't exist.
* GH-82695: Clarify `pathlib.Path.mkdir()` documentation (#114032)Barney Gale2024-01-231-3/+3
| | | | | | Remove a double negative in the documentation of `mkdir()`'s *exist_ok* parameter. Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
* GH-99334: Explain that `PurePath.is_relative_to()` is purely lexical. (#114031)Barney Gale2024-01-231-0/+7
|
* GH-79634: Accept path-like objects as pathlib glob patterns. (#114017)Barney Gale2024-01-201-0/+6
| | | | | | | | | Allow `os.PathLike` objects to be passed as patterns to `pathlib.Path.glob()` and `rglob()`. (It's already possible to use them in `PurePath.match()`) While we're in the area: - Allow empty glob patterns in `PathBase` (but not `Path`) - Speed up globbing in `PathBase` by generating paths with trailing slashes only as a final step, rather than for every intermediate directory. - Simplify and speed up handling of rare patterns involving both `**` and `..` segments.
* GH-110109: pathlib docs: bring `from_uri()` and `as_uri()` together. (#110312)Barney Gale2024-01-161-49/+61
| | | | | | | This is a very soft deprecation of `PurePath.as_uri()`. We instead document it as a `Path` method, and add a couple of sentences mentioning that it's also available in `PurePath`. Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
* GH-78988: Document `pathlib.Path.glob()` exception propagation. (#114036)Barney Gale2024-01-161-0/+4
| | | | We propagate the `OSError` from the `is_dir()` call on the top-level directory, and suppress all others.
* gh-112758: Updated pathlib documentation for PurePath.match (#112814)Taylor Packard2023-12-081-0/+3
|
* gh-101100: Silence Sphinx warnings when `ntpath` or `posixpath` are ↵Alex Waygood2023-12-071-1/+1
| | | | referenced (#112833)
* gh-103363: Add follow_symlinks argument to `pathlib.Path.owner()` and ↵Kamil Turek2023-12-041-4/+16
| | | | `group()` (#107962)
* gh-110745: add a newline argument to pathlib.Path.read_text (#110880)Junya Okabe2023-11-211-1/+3
| | | | Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com> Co-authored-by: Barney Gale <barney.gale@gmail.com>
* GH-107465: Add `pathlib.Path.from_uri()` classmethod. (#107640)Barney Gale2023-10-011-0/+36
| | | | | | | This method supports file URIs (including variants) as described in RFC 8089, such as URIs generated by `pathlib.Path.as_uri()` and `urllib.request.pathname2url()`. The method is added to `Path` rather than `PurePath` because it uses `os.fsdecode()`, and so its results vary from system to system. I intend to deprecate `PurePath.as_uri()` and move it to `Path` for the same reason. Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
* GH-109187: Improve symlink loop handling in `pathlib.Path.resolve()` (GH-109192)Barney Gale2023-09-261-5/+9
| | | | Treat symlink loops like other errors: in strict mode, raise `OSError`, and in non-strict mode, do not raise any exception.
* GH-70303: Emit FutureWarning when pathlib glob pattern ends with `**` ↵Barney Gale2023-08-041-0/+5
| | | | | | (GH-105413) In a future Python release, patterns with this ending will match both files and directories. Users may add a trailing slash to remove the warning.
* GH-100502: Add `pathlib.PurePath.pathmod` attribute (GH-106533)Barney Gale2023-07-191-0/+7
| | | | This instance attribute stores the implementation of `os.path` used for low-level path operations: either `posixpath` or `ntpath`.
* docs: clarify Path.suffix (GH-106650)Ned Batchelder2023-07-131-2/+3
|
* GH-105793: Add follow_symlinks argument to `pathlib.Path.is_dir()` and ↵Barney Gale2023-06-261-6/+18
| | | | | | | `is_file()` (GH-105794) Brings `pathlib.Path.is_dir()` and `in line with `os.DirEntry.is_dir()`, which will be important for implementing generic path walking and globbing. Likewise `is_file()`.
* GH-104375: Use `versionchanged` to describe new arguments in pathlib docs ↵Barney Gale2023-06-241-14/+14
| | | | (GH-104376)
* GH-89812: Add `pathlib.UnsupportedOperation` (GH-105926)Barney Gale2023-06-221-1/+43
| | | | | | | This new exception type is raised instead of `NotImplementedError` when a path operation is not supported. It can be raised from `Path.readlink()`, `symlink_to()`, `hardlink_to()`, `owner()` and `group()`. In a future version of pathlib, it will be raised by `AbstractPath` for these methods and others, such as `AbstractPath.mkdir()` and `unlink()`.
* GH-102613: Fast recursive globbing in `pathlib.Path.glob()` (GH-104512)Barney Gale2023-06-061-4/+8
| | | | | | | | | | | | | | This commit introduces a 'walk-and-match' strategy for handling glob patterns that include a non-terminal `**` wildcard, such as `**/*.py`. For this example, the previous implementation recursively walked directories using `os.scandir()` when it expanded the `**` component, and then **scanned those same directories again** when expanded the `*.py` component. This is wasteful. In the new implementation, any components following a `**` wildcard are used to build a `re.Pattern` object, which is used to filter the results of the recursive walk. A pattern like `**/*.py` uses half the number of `os.scandir()` calls; a pattern like `**/*/*.py` a third, etc. This new algorithm does not apply if either: 1. The *follow_symlinks* argument is set to `None` (its default), or 2. The pattern contains `..` components. In these cases we fall back to the old implementation. This commit also replaces selector classes with selector functions. These generators directly yield results rather calling through to their successors. A new internal `Path._glob()` method takes care to chain these generators together, which simplifies the lazy algorithm and slightly improves performance. It should also be easier to understand and maintain.
* GH-73435: Implement recursive wildcards in `pathlib.PurePath.match()` (#101398)Barney Gale2023-05-301-0/+11
| | | | | | | | `PurePath.match()` now handles the `**` wildcard as in `Path.glob()`, i.e. it matches any number of path segments. We now compile a `re.Pattern` object for the entire pattern. This is made more difficult by `fnmatch` not treating directory separators as special when evaluating wildcards (`*`, `?`, etc), and so we arrange the path parts onto separate *lines* in a string, and ensure we don't set `re.DOTALL`. Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com> Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
* GH-77609: Add follow_symlinks argument to `pathlib.Path.glob()` (GH-102616)Barney Gale2023-05-291-2/+18
| | | | | Add a keyword-only *follow_symlinks* parameter to `pathlib.Path.glob()` and`rglob()`. When *follow_symlinks* is `None` (the default), these methods follow symlinks except when evaluating "`**`" wildcards. When set to true or false, symlinks are always or never followed, respectively.
* GH-104484: Add case_sensitive argument to `pathlib.PurePath.match()` (GH-104565)thirumurugan2023-05-181-1/+6
| | | Co-authored-by: Barney Gale <barney.gale@gmail.com>
* gh-103960: Dark mode: invert image brightness (#103983)Hugo van Kemenade2023-05-101-0/+1
|
* GH-100479: Add `pathlib.PurePath.with_segments()` (GH-103975)Barney Gale2023-05-051-2/+26
| | | | | Add `pathlib.PurePath.with_segments()`, which creates a path object from arguments. This method is called whenever a derivative path is created, such as from `pathlib.PurePath.parent`. Subclasses may override this method to share information between path objects. Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
* GH-81079: Add case_sensitive argument to `pathlib.Path.glob()` (GH-102710)Barney Gale2023-05-041-2/+18
| | | | | | This argument allows case-sensitive matching to be enabled on Windows, and case-insensitive matching to be enabled on Posix. Co-authored-by: Steve Dower <steve.dower@microsoft.com>
generated by cgit v0.12 at 2026-02-12 16:33:40 (GMT)