8000 [WIP] GH-73991: Add `os.copy()` and friends by barneygale · Pull Request #119079 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

[WIP] GH-73991: Add os.copy() and friends #119079

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

[WIP] GH-73991: Add os.copy() and friends #119079

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
13e994b
GH-73991: Add `os.copyfile()` and friends
barneygale May 15, 2024
01afa3e
Move a few more tests over.
barneygale May 15, 2024
b3df117
Add `os.copy()`
barneygale May 15, 2024
ab09f78
Docs and tests fixes
barneygale May 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
GH-73991: Add os.copyfile() and friends 
Move these low-level file copy functions from `shutil` to `os`:

- `copyfileobj()`
- `copyfile()`
- `copymode()`
- `copystat()`

The names remain in `shutil` for backwards compatibility. The higher level
functions (which resemble the `cp` shell utility) also remain in `shutil`.
  • Loading branch information
@barneygale
barneygale committed May 15, 2024
commit 13e994b330af48641a54605a092982f30b3016af
106 changes: 106 additions & 0 deletions Doc/library/os.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,14 @@ Notes on the availability of these functions:
An alias for the built-in :exc:`OSError` exception.


.. exception:: SameFileError

This exception is raised if source and destination in :func:`copyfile`
are the same file.

.. versionadded:: 3.14


.. data:: name

The name of the operating system dependent module imported. The following
Expand Down Expand Up @@ -2184,6 +2192,104 @@ features:
Accepts a :term:`path-like object`.


.. function:: copyfileobj(fsrc, fdst[, length])

Copy the contents of the :term:`file-like object <file object>` *fsrc* to
the file-like object *fdst*. The integer *length*, if given, is the buffer
size. In particular, a negative *length* value means to copy the data
without looping over the source data in chunks; by default the data is read
in chunks to avoid uncontrolled memory consumption. Note that if the
current file position of the *fsrc* object is not 0, only the contents from
the current file position to the end of the file will be copied.

.. versionadded:: 3.14


.. function:: copyfile(src, dst, *, follow_symlinks=True)

Copy the contents (no metadata) of the file named *src* to a file named
*dst* and return *dst* in the most efficient way possible.
*src* and *dst* are :term:`path-like objects <path-like object>` or path
names given as strings.

*dst* must be the complete target file name; look at :func:`shutil.copy`
for a copy that accepts a target directory path. If *src* and *dst*
specify the same file, :exc:`SameFileError` is raised.

The destination location must be writable; otherwise, an :exc:`OSError`
exception will be raised. If *dst* already exists, it will be replaced.
Special files such as character or block devices and pipes cannot be
copied with this function.

If *follow_symlinks* is false and *src* is a symbolic link,
a new symbolic link will be created instead of copying the
file *src* points to.

.. audit-event:: os.copyfile src,dst os.copyfile

.. versionadded:: 3.14


.. function:: copymode(src, dst, *, follow_symlinks=True)

Copy the permission bits from *src* to *dst*. The file contents, owner, and
group are unaffected. *src* and *dst* are
:term:`path-like objects <path-like object>` or path names given as
strings. If *follow_symlinks* is false, and both *src* and *dst* are
symbolic links, :func:`copymode` will attempt to modify the mode of *dst*
itself (rather than the file it points to). This functionality is not
available on every platform; please see :func:`copystat` for more
information. If :func:`copymode` cannot modify symbolic links on the local
platform, and it is asked to do so, it will do nothing and return.

.. audit-event:: os.copymode src,dst os.copymode

.. versionadded:: 3.14


.. function:: copystat(src, dst, *, follow_symlinks=True)

Copy the permission bits, last access time, last modification time, and
flags from *src* to *dst*. On Linux, :func:`copystat` also copies the
"extended attributes" where possible. The file contents, owner, and group
are unaffected. *src* and *dst* are
:term:`path-like objects <path-like object>` or path names given as
strings.

If *follow_symlinks* is false, and *src* and *dst* both refer to symbolic
links, :func:`copystat` will operate on the symbolic links themselves
rather than the files the symbolic links refer to—reading the information
from the *src* symbolic link, and writing the information to the *dst*
symbolic link.

.. note::

Not all platforms provide the ability to examine and modify symbolic
links. Python itself can tell you what functionality is locally
available.

* If ``os.chmod in os.supports_follow_symlinks`` is ``True``,
:func:`copystat` can modify the permission bits of a symbolic link.

* If ``os.utime in os.supports_follow_symlinks`` is ``True``,
:func:`copystat` can modify the last access and modification times of
a symbolic link.

* If ``os.chflags in os.supports_follow_symlinks`` is ``True``,
:func:`copystat` can modify the flags of a symbolic link.
(``os.chflags`` is not available on all platforms.)

On platforms where some or all of this functionality is unavailable,
when asked to modify a symbolic link, :func:`copystat` will copy
everything it can. :func:`copystat` never returns failure.

Please see :data:`supports_follow_symlinks` for more information.

.. audit-event:: os.copystat src,dst os.copystat

.. versionadded:: 3.14


.. function:: fchdir(fd)

Change the current working directory to the directory represented by the file
Expand Down
84 changes: 5 additions & 79 deletions Doc/library/shutil.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,35 +39,12 @@ Directory and files operations

.. function:: copyfileobj(fsrc, fdst[, length])

Copy the contents of the :term:`file-like object <file object>` *fsrc* to the file-like object *fdst*.
The integer *length*, if given, is the buffer size. In particular, a negative
*length* value means to copy the data without looping over the source data in
chunks; by default the data is read in chunks to avoid uncontrolled memory
consumption. Note that if the current file position of the *fsrc* object is not
0, only the contents from the current file position to the end of the file will
be copied.
Alias of :func:`os.copyfileobj`.


.. function:: copyfile(src, dst, *, follow_symlinks=True)

Copy the contents (no metadata) of the file named *src* to a file named
*dst* and return *dst* in the most efficient way possible.
*src* and *dst* are :term:`path-like objects <path-like object>` or path names given as strings.

*dst* must be the complete target file name; look at :func:`~shutil.copy`
for a copy that accepts a target directory path. If *src* and *dst*
specify the same file, :exc:`SameFileError` is raised.

The destination location must be writable; otherwise, an :exc:`OSError`
exception will be raised. If *dst* already exists, it will be replaced.
Special files such as character or block devices and pipes cannot be
copied with this function.

If *follow_symlinks* is false and *src* is a symbolic link,
a new symbolic link will be created instead of copying the
file *src* points to.

.. audit-event:: shutil.copyfile src,dst shutil.copyfile
Alias of :func:`os.copyfile`.

.. versionchanged:: 3.3
:exc:`IOError` used to be raised instead of :exc:`OSError`.
Expand All @@ -85,72 +62,21 @@ Directory and files operations

.. exception:: SameFileError

This exception is raised if source and destination in :func:`copyfile`
are the same file.
Alias of :exc:`os.SameFileError`.

.. versionadded:: 3.4


.. function:: copymode(src, dst, *, follow_symlinks=True)

Copy the permission bits from *src* to *dst*. The file contents, owner, and
group are unaffected. *src* and *dst* are :term:`path-like objects <path-like object>` or path names
given as strings.
If *follow_symlinks* is false, and both *src* and *dst* are symbolic links,
:func:`copymode` will attempt to modify the mode of *dst* itself (rather
than the file it points to). This functionality is not available on every
platform; please see :func:`copystat` for more information. If
:func:`copymode` cannot modify symbolic links on the local platform, and it
is asked to do so, it will do nothing and return.

.. audit-event:: shutil.copymode src,dst shutil.copymode
Alias of :func:`os.copymode`.

.. versionchanged:: 3.3
Added *follow_symlinks* argument.

.. function:: copystat(src, dst, *, follow_symlinks=True)

Copy the permission bits, last access time, last modification time, and
flags from *src* to *dst*. On Linux, :func:`copystat` also copies the
"extended attributes" where possible. The file contents, owner, and
group are unaffected. *src* and *dst* are :term:`path-like objects <path-like object>` or path
names given as strings.

If *follow_symlinks* is false, and *src* and *dst* both
refer to symbolic links, :func:`copystat` will operate on
the symbolic links themselves rather than the files the
symbolic links refer to—reading the information from the
*src* symbolic link, and writing the information to the
*dst* symbolic link.

.. note::

Not all platforms provide the ability to examine and
modify symbolic links. Python itself can tell you what
functionality is locally available.

* If ``os.chmod in os.supports_follow_symlinks`` is
``True``, :func:`copystat` can modify the permission
bits of a symbolic link.

* If ``os.utime in os.supports_follow_symlinks`` is
``True``, :func:`copystat` can modify the last access
and modification times of a symbolic link.

* If ``os.chflags in os.supports_follow_symlinks`` is
``True``, :func:`copystat` can modify the flags of
a symbolic link. (``os.chflags`` is not available on
all platforms.)

On platforms where some or all of this functionality
is unavailable, when asked to modify a symbolic link,
:func:`copystat` will copy everything it can.
:func:`copystat` never returns failure.

Please see :data:`os.supports_follow_symlinks`
for more information.

.. audit-event:: shutil.copystat src,dst shutil.copystat
Alias of :func:`os.copystat`.

.. versionchanged:: 3.3
Added *follow_symlinks* argument and support for Linux extended attributes.
Expand Down
Loading
0