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

Docs: In param lists mark up multiple types correctly #116389

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
12 changes: 6 additions & 6 deletions Doc/library/ftplib.rst
Expand Up @@ -104,11 +104,11 @@ FTP objects
:param timeout:
A timeout in seconds for blocking operations like :meth:`connect`
(default: the global default timeout setting).
:type timeout: float | None
:type timeout: float or None

:param source_address:
|param_doc_source_address|
:type source_address: tuple | None
:type source_address: tuple or None

:param str encoding:
|param_doc_encoding|
Expand Down Expand Up @@ -178,11 +178,11 @@ FTP objects
:param timeout:
A timeout in seconds for the connection attempt
(default: the global default timeout setting).
:type timeout: float | None
:type timeout: float or None

:param source_address:
|param_doc_source_address|
:type source_address: tuple | None
:type source_address: tuple or None

.. audit-event:: ftplib.connect self,host,port ftplib.FTP.connect

Expand Down Expand Up @@ -483,11 +483,11 @@ FTP_TLS objects
:param timeout:
A timeout in seconds for blocking operations like :meth:`~FTP.connect`
(default: the global default timeout setting).
:type timeout: float | None
:type timeout: float or None

:param source_address:
|param_doc_source_address|
:type source_address: tuple | None
:type source_address: tuple or None

:param str encoding:
|param_doc_encoding|
Expand Down
6 changes: 3 additions & 3 deletions Doc/library/functions.rst
Expand Up @@ -528,15 +528,15 @@ are always available. They are listed here in alphabetical order.

:param expression:
A Python expression.
:type expression: :class:`str` | :ref:`code object <code-objects>`
:type expression: str or :ref:`code object <code-objects>`

:param globals:
The global namespace (default: ``None``).
:type globals: :class:`dict` | ``None``
:type globals: dict or None

:param locals:
The local namespace (default: ``None``).
:type locals: :term:`mapping` | ``None``
:type locals: :term:`mapping` or None

:returns: The result of the evaluated expression.
:raises: Syntax errors are reported as exceptions.
Expand Down
8 changes: 4 additions & 4 deletions Doc/library/logging.rst
Expand Up @@ -873,21 +873,21 @@ wire).

:param args: Variable data to merge into the *msg* argument
to obtain the event description.
:type args: tuple | dict[str, typing.Any]
:type args: tuple or dict[str, typing.Any]

:param exc_info: An exception tuple with the current exception information,
as returned by :func:`sys.exc_info`,
or ``None`` if no exception information is available.
:type exc_info: tuple[type[BaseException], BaseException, types.TracebackType] | None
:type exc_info: tuple[type[BaseException], BaseException, types.TracebackType] or None
Copy link
Member

Choose a reason for hiding this comment

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

Is this one still perhaps a bit too complex for the docs? Not sure how it could be simplified, though

Copy link
Contributor Author

Choose a reason for hiding this comment

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

It is definitely complex. In this case, I'd say readability is definitely improved using or iso. |.


:param func: The name of the function or method
from which the logging call was invoked.
:type func: str | None
:type func: str or None

:param sinfo: A text string representing stack information
from the base of the stack in the current thread,
up to the logging call.
:type sinfo: str | None
:type sinfo: str or None

.. method:: getMessage()

Expand Down
2 changes: 1 addition & 1 deletion Doc/library/multiprocessing.shared_memory.rst
Expand Up @@ -56,7 +56,7 @@ copying of data.
The unique name for the requested shared memory, specified as a string.
When creating a new shared memory block, if ``None`` (the default)
is supplied for the name, a novel name will be generated.
:type name: str | None
:type name: str or None

:param bool create:
Control whether a new shared memory block is created (``True``)
Expand Down
16 changes: 8 additions & 8 deletions Doc/library/sqlite3.rst
Expand Up @@ -300,7 +300,7 @@ Module functions
or ``None`` to disable opening transactions implicitly.
Has no effect unless :attr:`Connection.autocommit` is set to
:const:`~sqlite3.LEGACY_TRANSACTION_CONTROL` (the default).
:type isolation_level: str | None
:type isolation_level: str or None

:param bool check_same_thread:
If ``True`` (default), :exc:`ProgrammingError` will be raised
Expand Down Expand Up @@ -740,7 +740,7 @@ Connection objects
The callable must return :ref:`a type natively supported by SQLite
<sqlite3-types>`.
Set to ``None`` to remove an existing SQL function.
:type func: :term:`callback` | None
:type func: :term:`callback` or None

:param bool deterministic:
If ``True``, the created SQL function is marked as
Expand Down Expand Up @@ -791,7 +791,7 @@ Connection objects
is controlled by *n_arg*.

Set to ``None`` to remove an existing SQL aggregate function.
:type aggregate_class: :term:`class` | None
:type aggregate_class: :term:`class` or None

Example:

Expand Down Expand Up @@ -857,7 +857,7 @@ Connection objects
If used with a version of SQLite older than 3.25.0,
which does not support aggregate window functions.

:type aggregate_class: :term:`class` | None
:type aggregate_class: :term:`class` or None

.. versionadded:: 3.11

Expand Down Expand Up @@ -1123,7 +1123,7 @@ Connection objects
SQLite will come up with an entry point name of its own;
see the SQLite docs `Loading an Extension`_ for details.

:type entrypoint: str | None
:type entrypoint: str or None

.. audit-event:: sqlite3.load_extension connection,path sqlite3.Connection.load_extension

Expand All @@ -1148,7 +1148,7 @@ Connection objects
An optional ``LIKE`` pattern for database objects to dump, e.g. ``prefix_%``.
If ``None`` (the default), all database objects will be included.

:type filter: str | None
:type filter: str or None

Example:

Expand Down Expand Up @@ -1191,7 +1191,7 @@ Connection objects
the *remaining* number of pages still to be copied,
and the *total* number of pages.
Defaults to ``None``.
:type progress: :term:`callback` | None
:type progress: :term:`callback` or None

:param str name:
The name of the database to back up.
Expand Down Expand Up @@ -1523,7 +1523,7 @@ Cursor objects
A :class:`!dict` if named placeholders are used.
A :term:`!sequence` if unnamed placeholders are used.
See :ref:`sqlite3-placeholders`.
:type parameters: :class:`dict` | :term:`sequence`
:type parameters: dict or :term:`sequence`

:raises ProgrammingError:
If *sql* contains more than one SQL statement.
Expand Down