Skip to content
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.

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

gh-101100: Fix Sphinx nitpicks in library/tempfile.rst #112886

Merged
merged 2 commits into from
Dec 9, 2023
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
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
52 changes: 29 additions & 23 deletions Doc/library/tempfile.rst
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ This module creates temporary files and directories. It works on all
supported platforms. :class:`TemporaryFile`, :class:`NamedTemporaryFile`,
:class:`TemporaryDirectory`, and :class:`SpooledTemporaryFile` are high-level
interfaces which provide automatic cleanup and can be used as
context managers. :func:`mkstemp` and
:term:`context manager`\s. :func:`mkstemp` and
AlexWaygood marked this conversation as resolved.
Show resolved Hide resolved
:func:`mkdtemp` are lower-level functions which require manual cleanup.

All the user-callable functions and constructors take additional arguments which
Expand All @@ -41,7 +41,7 @@ The module defines the following user-callable items:
this; your code should not rely on a temporary file created using this
function having or not having a visible name in the file system.

The resulting object can be used as a context manager (see
The resulting object can be used as a :term:`context manager` (see
:ref:`tempfile-examples`). On completion of the context or
destruction of the file object the temporary file will be removed
from the filesystem.
Expand Down Expand Up @@ -87,9 +87,9 @@ The module defines the following user-callable items:
determine whether and how the named file should be automatically deleted.

The returned object is always a :term:`file-like object` whose :attr:`!file`
attribute is the underlying true file object. This :term:`file-like object`
attribute is the underlying true file object. This file-like object
can be used in a :keyword:`with` statement, just like a normal file. The
name of the temporary file can be retrieved from the :attr:`name` attribute
name of the temporary file can be retrieved from the :attr:`!name` attribute
of the returned file-like object. On Unix, unlike with the
:func:`TemporaryFile`, the directory entry does not get unlinked immediately
after the file creation.
Expand Down Expand Up @@ -151,18 +151,20 @@ The module defines the following user-callable items:
contents are written to disk and operation proceeds as with
:func:`TemporaryFile`.

The resulting file has one additional method, :func:`rollover`, which
causes the file to roll over to an on-disk file regardless of its size.
.. method:: SpooledTemporaryFile.rollover

The returned object is a file-like object whose :attr:`_file` attribute
The resulting file has one additional method, :meth:`!rollover`, which
causes the file to roll over to an on-disk file regardless of its size.

The returned object is a file-like object whose :attr:`!_file` attribute
is either an :class:`io.BytesIO` or :class:`io.TextIOWrapper` object
(depending on whether binary or text *mode* was specified) or a true file
object, depending on whether :func:`rollover` has been called. This
object, depending on whether :meth:`rollover` has been called. This
file-like object can be used in a :keyword:`with` statement, just like
a normal file.

.. versionchanged:: 3.3
the truncate method now accepts a ``size`` argument.
the truncate method now accepts a *size* argument.

.. versionchanged:: 3.8
Added *errors* parameter.
Expand All @@ -176,24 +178,28 @@ The module defines the following user-callable items:
.. class:: TemporaryDirectory(suffix=None, prefix=None, dir=None, ignore_cleanup_errors=False, *, delete=True)

This class securely creates a temporary directory using the same rules as :func:`mkdtemp`.
The resulting object can be used as a context manager (see
The resulting object can be used as a :term:`context manager` (see
:ref:`tempfile-examples`). On completion of the context or destruction
of the temporary directory object, the newly created temporary directory
and all its contents are removed from the filesystem.

The directory name can be retrieved from the :attr:`name` attribute of the
returned object. When the returned object is used as a context manager, the
:attr:`name` will be assigned to the target of the :keyword:`!as` clause in
the :keyword:`with` statement, if there is one.

The directory can be explicitly cleaned up by calling the
:func:`cleanup` method. If *ignore_cleanup_errors* is true, any unhandled
exceptions during explicit or implicit cleanup (such as a
:exc:`PermissionError` removing open files on Windows) will be ignored,
and the remaining removable items deleted on a "best-effort" basis.
Otherwise, errors will be raised in whatever context cleanup occurs
(the :func:`cleanup` call, exiting the context manager, when the object
is garbage-collected or during interpreter shutdown).
.. attribute:: TemporaryDirectory.name

The directory name can be retrieved from the :attr:`!name` attribute of the
returned object. When the returned object is used as a :term:`context manager`, the
:attr:`!name` will be assigned to the target of the :keyword:`!as` clause in
the :keyword:`with` statement, if there is one.

.. method:: TemporaryDirectory.cleanup

The directory can be explicitly cleaned up by calling the
:meth:`!cleanup` method. If *ignore_cleanup_errors* is true, any unhandled
exceptions during explicit or implicit cleanup (such as a
:exc:`PermissionError` removing open files on Windows) will be ignored,
and the remaining removable items deleted on a "best-effort" basis.
Otherwise, errors will be raised in whatever context cleanup occurs
(the :meth:`!cleanup` call, exiting the context manager, when the object
is garbage-collected or during interpreter shutdown).
Comment on lines +186 to +202
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

Before After
image image


The *delete* parameter can be used to disable cleanup of the directory tree
upon exiting the context. While it may seem unusual for a context manager
Expand Down
1 change: 0 additions & 1 deletion Doc/tools/.nitignore
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,6 @@ Doc/library/string.rst
Doc/library/subprocess.rst
Doc/library/syslog.rst
Doc/library/tarfile.rst
Doc/library/tempfile.rst
Doc/library/termios.rst
Doc/library/test.rst
Doc/library/tkinter.rst
Expand Down
Loading