summaryrefslogtreecommitdiffstats
path: root/Doc/library/shutil.rst
Commit message (Collapse)AuthorAgeFilesLines
* [3.13] Improve the `rmtree` doc for `dir_fd` param addition in 3.11 ↵Miss Islington (bot)2024-05-131-1/+1
| | | | | | (GH-118964) (#118991) Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
* [3.13] docs: module page titles should not start with a link to themselves ↵Miss Islington (bot)2024-05-081-2/+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>
* docs: typo: tiny grammar change: "pointed by" -> "pointed to by" (#118411)Andrew Zipperer2024-05-021-2/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | * docs: tiny grammar change: "pointed by" -> "pointed to by" This commit uses "file pointed to by" to replace "file pointed by" in - doc for shutil.copytree - docstring for shutil.copytree - docstring _abc.PathBase.open - docstring for pathlib.Path.open - doc for os.copy_file_range - doc for os.splice The docs use "file pointed to by" more frequently than "file pointed by". So, this commit replaces the uses of "file pointed by" in order to make the uses consistent through the docs. ```bash $ grep -ri 'pointed to by' cpython/ ``` yields more results than ```bash $ grep -ri 'pointed by' cpython/ ``` Separately: There are two occurrences of "tree pointed by": - cpython/Doc/library/xml.etree.elementtree.rst for `xml.etree.ElementInclude.include` - cpython/Lib/xml/etree/ElementInclude.py for `include` For those uses of "tree pointed by", I expect "tree pointed to by" instead. However, I found enough uses online of (a) "tree pointed by" rather than (b) "tree pointed to by" to convince me that (a) is in common use. So, this commit does not replace those occurrences of "tree pointed by" to "tree pointed to by". But I will replace them if a reviewer believes it is correct to replace them. * docs: typo: "exists and executable" -> "exists and is executable" --------- Co-authored-by: Andrew-Zipperer <atzipperer@gmail.com>
* GH-118174: specify the type for the path argument of shutil.whichFilipe Laíns2024-05-011-2/+3
|
* bpo-18108: Adding dir_fd and follow_symlinks keyword args to shutil.chown ↵tahia2024-04-221-1/+5
| | | | | | | | | | | (GH-15811) * Adding dir_fd and follow_symlinks keyword args to shutil.chown * Extending test_shutil.TestShutil.test_chown to include new kwargs * Updating shutil.chown documentation Co-authored-by: Serhiy Storchaka <storchaka@gmail.com> Co-authored-by: Berker Peksag <berker.peksag@gmail.com> Co-authored-by: Zachary Ware <zachary.ware@gmail.com>
* gh-115664: Fix chronological ordering of versionadded and versionchanged ↵Brian Schubert2024-02-191-4/+4
| | | | directives (#115676)
* docs: Add glossary term references to shutil docs (#115559)Brian Schubert2024-02-161-4/+4
| | | Add glossary term references to shutil docs
* gh-113803: Fix inaccurate documentation for shutil.move when dst is an ↵Dai Wentao2024-02-041-11/+14
| | | | | | existing directory (#113837) * fix the usage of dst and destination in shutil.move doc * update shutil.move doc
* Move "format" param doc of shutil.make_archive() on its own paragraph ↵Michal Kaptur2024-02-021-1/+3
| | | | (GH-103829)
* Docs: align usage of versionadded/versionchanged with recommended practice ↵Erlend E. Aasland2024-01-221-2/+2
| | | | | | (#114409) Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
* Add a versionchanged directive for gh-94692 (GH-112846)Serhiy Storchaka2023-12-081-0/+2
| | | Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
* gh-81441: shutil.rmtree() FileNotFoundError race condition (GH-14064)Jeffrey Kintscher2023-12-051-0/+4
| | | | | | | Ignore missing files and directories while enumerating directory entries in shutil.rmtree(). Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
* gh-109590: Update shutil.which on Windows to prefer a PATHEXT extension on ↵Charles Machalow2023-10-021-0/+6
| | | | | executable files (GH-109995) The default arguments for shutil.which() request an executable file, but extensionless files are not executable on Windows and should be ignored.
* gh-101100: Sphinx warnings: pick the low hanging fruits (GH-107386)Serhiy Storchaka2023-07-291-1/+1
|
* gh-83006: Document behavior of `shutil.disk_usage` for non-mounted ↵Matthieu Caneill2023-07-221-0/+6
| | | | filesystems on Unix (#107031)
* gh-106892: Use roles :data: and :const: for referencing module variables ↵Serhiy Storchaka2023-07-211-1/+1
| | | | (GH-106894)
* gh-102950: Implement PEP 706 – Filter for tarfile.extractall (#102953)Petr Viktorin2023-04-241-6/+20
|
* GH-75586: Make shutil.which() on Windows more consistent with the OS (GH-103179)Charles Machalow2023-04-041-7/+27
|
* gh-102828: add onexc arg to shutil.rmtree. Deprecate onerror. (#102829)Irit Katriel2023-03-191-9/+15
|
* gh-74696: Pass root_dir to custom archivers which support it (GH-94251)Serhiy Storchaka2022-10-051-2/+12
| | | | Co-authored-by: Éric <merwok@netwok.org>
* gh-91838: Use HTTPS links in docs for resources which redirect to HTTPS ↵Serhiy Storchaka2022-08-041-1/+1
| | | | | | | | | | (GH-95527) If an HTTP link is redirected to a same looking HTTPS link, the latter can be used directly without changes in readability and behavior. It protects from a men-in-the-middle attack. This change does not affect Python examples.
* Docs: remove redundant "adverb-adjective" hyphens from compound modifiers ↵Ned Batchelder2022-07-051-1/+1
| | | | | (GH-94551) Discussion: https://discuss.python.org/t/slight-grammar-fix-throughout-adverbs-dont-need-hyphen/17021
* gh-74696: Do not change the current working directory in ↵Serhiy Storchaka2022-06-221-1/+7
| | | | | | | | | | | shutil.make_archive() if possible (GH-93160) It is no longer changed when create a zip or tar archive. It is still changed for custom archivers registered with shutil.register_archive_format() if root_dir is not None. Co-authored-by: Éric <merwok@netwok.org> Co-authored-by: Łukasz Langa <lukasz@langa.pl>
* gh-91783: Document security considerations for shutil.unpack_archive (#91844)Sam Ezeh2022-05-021-1/+7
|
* gh-84714: Add behavior if dst file exists (#91867)slateny2022-05-021-1/+2
|
* gh-88513: clarify shutil.copytree's dirs_exist_ok arg (GH-91434)Jack DeVries2022-04-121-6/+11
| | | | | * add a paragraph to document this kwarg in detail * update docstring in the source accordingly
* bpo-40982: shutil docs: Remove outdated copytree() example (GH-24778)Zackery Spytz2022-04-051-36/+1
| | | | It is not preferable to keep a copy of the implementation in the docs.
* bpo-46245: Add optional parameter dir_fd in shutil.rmtree() (GH-30365)Serhiy Storchaka2022-03-091-2/+8
|
* bpo-42174: fallback to sane values if the columns or lines are 0 in ↵Filipe Laíns2021-10-191-0/+4
| | | | | | | | | | | | | get_terminal_size (GH-29046) I considered only falling back when both were 0, but that still seems wrong, and the highly popular rich[1] library does it this way, so I thought we should probably inherit that behavior. [1] https://github.com/willmcgugan/rich Signed-off-by: Filipe Laíns <lains@riseup.net> Co-authored-by: Łukasz Langa <lukasz@langa.pl>
* bpo-30511: Add note on thread safety to shutil.make_archive() (#26933)andrei kulakov2021-07-211-0/+4
| | | Co-authored-by: Łukasz Langa <lukasz@langa.pl>
* bpo-43200: Fix link to shutil.copy() in the shutil doc (GH-24505)Zackery Spytz2021-02-131-2/+3
| | | Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>
* [doc] Fix erroneous backslashes in signatures and names (GH-23658)Andre Delfino2020-12-171-1/+1
| | | | | The issue being resolved is shown in the 3.10 docs (if you select docs for older versions you won't see a visual glitch). The newer sphinx version that produces the 3.10 docs doesn't treat the backslash to escape things in some situations it previously did.
* Fix incorrect parameter name (GH-22613)Xie Yanbo2020-10-101-1/+1
| | | Automerge-Triggered-By: @Mariatta
* bpo-41646: Mention path-like objects support in the docs for shutil.copy() ↵Zackery Spytz2020-09-141-3/+3
| | | | (GH-22208)
* bpo-22021: Update root_dir and base_dir documentation in shutil (GH-10367)Lysandros Nikolaou2020-06-081-3/+47
| | | | | Also added an example in shutil in order to make more clear how they are to be used. Initially reported by Weinan Li on bpo.
* bpo-39184: Add audit events to functions in `fcntl`, `msvcrt`, `os`, ↵Saiyang Gou2020-02-131-0/+20
| | | | `resource`, `shutil`, `signal`, `syslog` (GH-18407)
* bpo-32689: Updates shutil.move to allow for Path objects to be used as ↵Maxwell A McKinnon2019-10-011-0/+3
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | source arg (GH-15326) Important work originally done by @emilyemorehouse two years ago and nearly ready to go in. This bug has affected many people and in some cases has been a dealbreaker to the adoption of the otherwise wonderful pathlib and PEP519. https://stackoverflow.com/questions/33625931/copy-file-with-pathlib-in-python. This adds the outstanding test request from that PR @vstinner (https://github.com/python/cpython/pull/5393). Test fails without the change, passes with it, along with every other test in test_shutil. Some variants were experimented with to make the one line change and the most performant one was picked. # Added Test for PathLike directory destination, the current fail case ``` Lib/test/test_shutil.py::TestMove::test_move_file_pathlike FAILED [100%] ============================================================== FAILURES =============================================================== __________________________________________________ TestMove.test_move_file_pathlike ___________________________________________________ self = <test.test_shutil.TestMove testMethod=test_move_file_pathlike> def test_move_file_pathlike(self): # Move a file to another location on the same filesystem. src = pathlib.Path(self.src_file) > self._check_move_file(src, self.dst_dir, self.dst_file) Lib/test/test_shutil.py:1563: _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ Lib/test/test_shutil.py:1545: in _check_move_file shutil.move(src, dst) /Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/shutil.py:562: in move real_dst = os.path.join(dst, _basename(src)) _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ path = PosixPath('/var/folders/r2/psq74t5x3nbfzlph8bh2pvdw0000gn/T/tmp9ie0wh9_/foo') def _basename(path): # A basename() variant which first strips the trailing slash, if present. # Thus we always get the last component of the path, even for directories. sep = os.path.sep + (os.path.altsep or '') > return os.path.basename(path.rstrip(sep)) E AttributeError: 'PosixPath' object has no attribute 'rstrip' /Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/shutil.py:526: AttributeError ============================================== 1 failed, 102 deselected in 0.30 seconds =============================================== ``` After change: ``` ========================================================= test session starts ========================================================= platform darwin -- Python 3.7.4, pytest-5.0.1, py-1.8.0, pluggy-0.12.0 -- /Users/maxwellmckinnon/.venvs/TA3.7/bin/python3.7 cachedir: .pytest_cache rootdir: /Users/maxwellmckinnon/dev/cpython plugins: cov-2.7.1, mock-1.10.4 collected 103 items / 102 deselected / 1 selected Lib/test/test_shutil.py::TestMove::test_move_file_pathlike PASSED [100%] ============================================== 1 passed, 102 deselected in 0.06 seconds =============================================== ``` Running all the tests in test_shutil.py ``` ╰─ pytest Lib/test/test_shutil.py -v ========================================================= test session starts ========================================================= platform darwin -- Python 3.7.4, pytest-5.0.1, py-1.8.0, pluggy-0.12.0 -- /Users/maxwellmckinnon/.venvs/TA3.7/bin/python3.7 cachedir: .pytest_cache rootdir: /Users/maxwellmckinnon/dev/cpython plugins: cov-2.7.1, mock-1.10.4 collected 103 items Lib/test/test_shutil.py::TestShutil::test_chown PASSED [ 0%] Lib/test/test_shutil.py::TestShutil::test_copy PASSED [ 1%] ... Lib/test/test_shutil.py::TermsizeTests::test_stty_match SKIPPED [ 99%] Lib/test/test_shutil.py::PublicAPITests::test_module_all_attribute PASSED [100%] ================================================ 96 passed, 7 skipped in 1.25 seconds ================================================= ``` # Performance Considerations Is it considered poor form to get rid of _basename altogether and make use of pathlib in the move function? I'm not sure if the idea is for all these modules to strictly avoid circular dependencies. They are already using os.path which is just as much a citizen in 3.8 as pathlib right? e.g. `real_dst = os.path.join(dst, _basename(src))` becomes `real_dst = Path(dst) / Path(src).name` I've looked around and familiarized myself, and I now think importing pathlib here is fine. My only remaining concern is that of performance. Here's the performance difference for this step. ``` In [46]: %timeit real_dst = os.path.join("a/b/c", _basename('b/')) 2.71 µs ± 62.6 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each) In [47]: %timeit real_dst = Path("a/b/c") / Path('b/').name 12.4 µs ± 65.3 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each) ``` Is 10us significant or insignificant compared to the least expensive operation this function will do? I don't know. Let's find out. ``` In [55]: %timeit os.rename('/tmp/a/a.txt', '/tmp/a/b.txt'); os.rename('/tmp/a/b.txt', '/tmp/a/a.txt') 124 µs ± 2.18 µs per loop (mean ± std. dev. of 7 runs, 10000 loops each) ``` 62us to rename. 10us seems significant enough that we wouldn't want to favor the Path sugar suggestion. 16% speed decrease from adding the 10us. What do people think? I was hoping to get to use pathlib.Path here, but I suspect for this low level move, it should be as fast as possible, and 16% is not worth one line of sugary code to me. https://bugs.python.org/issue32689 Automerge-Triggered-By: @gvanrossum
* bpo-26468: Doc: improve the documentation of shutil.copy2 when it can fail. ↵Windson yang2019-09-131-1/+2
| | | | (GH-13765)
* Clarify that shutil's copy functions can accept path-like values (GH-15141)Boris Verhovsky2019-09-091-3/+5
|
* bpo-37834: Normalise handling of reparse points on Windows (GH-15231)Steve Dower2019-08-211-0/+4
| | | | | | | | | | bpo-37834: Normalise handling of reparse points on Windows * ntpath.realpath() and nt.stat() will traverse all supported reparse points (previously was mixed) * nt.lstat() will let the OS traverse reparse points that are not name surrogates (previously would not traverse any reparse point) * nt.[l]stat() will only set S_IFLNK for symlinks (previous behaviour) * nt.readlink() will read destinations for symlinks and junction points only bpo-1311: os.path.exists('nul') now returns True on Windows * nt.stat('nul').st_mode is now S_IFCHR (previously was an error)
* bpo-37390: Add audit event table to documentations (GH-14406)Steve Dower2019-06-271-3/+3
| | | Also updates some (unreleased) event names to be consistent with the others.
* bpo-37363: Add audit events for a range of modules (GH-14301)Steve Dower2019-06-241-0/+6
|
* bpo-36610: shutil.copyfile(): use sendfile() on Linux only (GH-13675)Giampaolo Rodola2019-05-301-2/+1
| | | | ...and avoid using it on Solaris as it can raise EINVAL if offset is equal or bigger than the size of the file
* Hide module name from local (anchor) links in shutil docs (GH-6695)Aurelio Jargas2019-05-111-4/+4
|
* bpo-30661: Improve docs for tarfile pax change and effect on shutil (GH-12635)CAM Gerlach2019-04-071-1/+5
| | | | The shutil archive creation helpers use the default tarfile format, so that API is also switching to use `pax` by default.
* bpo-36103: change default buffer size of shutil.copyfileobj() (GH-12115)Inada Naoki2019-03-021-1/+1
| | | | | | | | | | | | | | | | It is changed from 16KiB to 64KiB. The previous default value is used since 1990. coreutils chose 128 KiB as minimum buffer size for block device I/O. But shutil.copyfileobj() can be used for non block devices. So I choose more conservative value. As my quick benchmark, performance difference between 64KiB and 128 KiB is up to ~5%. On the other hand, performance difference between 32 KiB and 64 KiB can be more than 10% when file is fully buffered. This is why 64 KiB is rational value.
* bpo-18283: Add support for bytes to shutil.which (GH-11818)Cheryl Sabella2019-02-131-0/+3
|
* bpo-20849: add dirs_exist_ok arg to shutil.copytree (patch by Josh Bronson)jab2018-12-281-7/+12
|
* bpo-34260, shutil: fix copy2 and copystat documentation (GH-8523)Zsolt Cserna2018-10-231-1/+1
| | | | | | | | | | Fix the documentation of copy2, as it does not copy file ownership (user and group), only mode, mtime, atime and flags. The original text was confusing to developers as it suggested that this command is the same as 'cp -p', but according to cp(1), '-p' copies file ownership as well. Clarify which metadata is copied by shutil.copystat in its docstring.
* bpo-11233: Create availability directive for documentation (GH-9692)Cheryl Sabella2018-10-121-2/+2
| | | | | | Replace "Availability: xxx" with ".. availability:: xxx" in the doc. Original patch by Georg Brandl. Co-Authored-By: Georg Brandl <georg@python.org>
generated by cgit v0.12 at 2024-11-25 18:09:43 (GMT)