Skip to content

Commit

Permalink
Docs: Fix Sphinx warnings in sys.rst (#108106)
Browse files Browse the repository at this point in the history 
- Mark up named tuple attributes as attributes
- Remove links for external functions
- io.BufferedIOBase has no 'buffer' attribute;
  remove the link and mark up using :attr:`!buffer`
- (Re)format some tables as bullet lists:
  - sys._emscripten_info
  - sys.hash_info
  - sys.int_info
  - sys.thread_info
- In the paragraphs mentioning 'f_trace_lines' and 'f_trace_opcodes',
  add links to the frame objects reference.

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
  • Loading branch information
@erlend-aasland @AlexWaygood @AA-Turner
3 people committed Aug 20, 2023
1 parent beffb30 commit 29fa7af
Show file tree
Hide file tree
Showing 3 changed files with 153 additions and 115 deletions.
265 changes: 152 additions & 113 deletions Doc/library/sys.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -333,23 +333,21 @@ always available.
*wasm32-emscripten* platform. The named tuple is provisional and may change
in the future.

.. tabularcolumns:: |l|L|

+-----------------------------+----------------------------------------------+
| Attribute | Explanation |
+=============================+==============================================+
| :const:`emscripten_version` | Emscripten version as tuple of ints |
| | (major, minor, micro), e.g. ``(3, 1, 8)``. |
+-----------------------------+----------------------------------------------+
| :const:`runtime` | Runtime string, e.g. browser user agent, |
| | ``'Node.js v14.18.2'``, or ``'UNKNOWN'``. |
+-----------------------------+----------------------------------------------+
| :const:`pthreads` | ``True`` if Python is compiled with |
| | Emscripten pthreads support. |
+-----------------------------+----------------------------------------------+
| :const:`shared_memory` | ``True`` if Python is compiled with shared |
| | memory support. |
+-----------------------------+----------------------------------------------+
.. attribute:: _emscripten_info.emscripten_version

Emscripten version as tuple of ints (major, minor, micro), e.g. ``(3, 1, 8)``.

.. attribute:: _emscripten_info.runtime

Runtime string, e.g. browser user agent, ``'Node.js v14.18.2'``, or ``'UNKNOWN'``.

.. attribute:: _emscripten_info.pthreads

``True`` if Python is compiled with Emscripten pthreads support.

.. attribute:: _emscripten_info.shared_memory

``True`` if Python is compiled with shared memory support.

.. availability:: Emscripten.

Expand Down Expand Up @@ -515,28 +513,62 @@ always available.
The :term:`named tuple` *flags* exposes the status of command line
flags. The attributes are read only.

============================== ==============================================================================================================
attribute flag
============================== ==============================================================================================================
:const:`debug` :option:`-d`
:const:`inspect` :option:`-i`
:const:`interactive` :option:`-i`
:const:`isolated` :option:`-I`
:const:`optimize` :option:`-O` or :option:`-OO`
:const:`dont_write_bytecode` :option:`-B`
:const:`no_user_site` :option:`-s`
:const:`no_site` :option:`-S`
:const:`ignore_environment` :option:`-E`
:const:`verbose` :option:`-v`
:const:`bytes_warning` :option:`-b`
:const:`quiet` :option:`-q`
:const:`hash_randomization` :option:`-R`
:const:`dev_mode` :option:`-X dev <-X>` (:ref:`Python Development Mode <devmode>`)
:const:`utf8_mode` :option:`-X utf8 <-X>`
:const:`safe_path` :option:`-P`
:const:`int_max_str_digits` :option:`-X int_max_str_digits <-X>` (:ref:`integer string conversion length limitation <int_max_str_digits>`)
:const:`warn_default_encoding` :option:`-X warn_default_encoding <-X>`
============================== ==============================================================================================================
.. list-table::

* - .. attribute:: flags.debug
- :option:`-d`

* - .. attribute:: flags.inspect
- :option:`-i`

* - .. attribute:: flags.interactive
- :option:`-i`

* - .. attribute:: flags.isolated
- :option:`-I`

* - .. attribute:: flags.optimize
- :option:`-O` or :option:`-OO`

* - .. attribute:: flags.dont_write_bytecode
- :option:`-B`

* - .. attribute:: flags.no_user_site
- :option:`-s`

* - .. attribute:: flags.no_site
- :option:`-S`

* - .. attribute:: flags.ignore_environment
- :option:`-E`

* - .. attribute:: flags.verbose
- :option:`-v`

* - .. attribute:: flags.bytes_warning
- :option:`-b`

* - .. attribute:: flags.quiet
- :option:`-q`

* - .. attribute:: flags.hash_randomization
- :option:`-R`

* - .. attribute:: flags.dev_mode
- :option:`-X dev <-X>` (:ref:`Python Development Mode <devmode>`)

* - .. attribute:: flags.utf8_mode
- :option:`-X utf8 <-X>`

* - .. attribute:: flags.safe_path
- :option:`-P`

* - .. attribute:: flags.int_max_str_digits
- :option:`-X int_max_str_digits <-X>`
(:ref:`integer string conversion length limitation <int_max_str_digits>`)

* - .. attribute:: flags.warn_default_encoding
- :option:`-X warn_default_encoding <-X>`

.. versionchanged:: 3.2
Added ``quiet`` attribute for the new :option:`-q` flag.
Expand Down Expand Up @@ -923,8 +955,8 @@ always available.
| | a domain controller. |
+---------------------------------------+---------------------------------+

This function wraps the Win32 :c:func:`GetVersionEx` function; see the
Microsoft documentation on :c:func:`OSVERSIONINFOEX` for more information
This function wraps the Win32 :c:func:`!GetVersionEx` function; see the
Microsoft documentation on :c:func:`!OSVERSIONINFOEX` for more information
about these fields.

*platform_version* returns the major version, minor version and
Expand Down Expand Up @@ -982,28 +1014,37 @@ always available.
implementation. For more details about hashing of numeric types, see
:ref:`numeric-hash`.

+---------------------+--------------------------------------------------+
| attribute | explanation |
+=====================+==================================================+
| :const:`width` | width in bits used for hash values |
+---------------------+--------------------------------------------------+
| :const:`modulus` | prime modulus P used for numeric hash scheme |
+---------------------+--------------------------------------------------+
| :const:`inf` | hash value returned for a positive infinity |
+---------------------+--------------------------------------------------+
| :const:`nan` | (this attribute is no longer used) |
+---------------------+--------------------------------------------------+
| :const:`imag` | multiplier used for the imaginary part of a |
| | complex number |
+---------------------+--------------------------------------------------+
| :const:`algorithm` | name of the algorithm for hashing of str, bytes, |
| | and memoryview |
+---------------------+--------------------------------------------------+
| :const:`hash_bits` | internal output size of the hash algorithm |
+---------------------+--------------------------------------------------+
| :const:`seed_bits` | size of the seed key of the hash algorithm |
+---------------------+--------------------------------------------------+
.. attribute:: hash_info.width

The width in bits used for hash values

.. attribute:: hash_info.modulus

The prime modulus P used for numeric hash scheme

.. attribute:: hash_info.inf

The hash value returned for a positive infinity

.. attribute:: hash_info.nan

(This attribute is no longer used)

.. attribute:: hash_info.imag

The multiplier used for the imaginary part of a complex number

.. attribute:: hash_info.algorithm

The name of the algorithm for hashing of str, bytes, and memoryview

.. attribute:: hash_info.hash_bits

The internal output size of the hash algorithm

.. attribute:: hash_info.seed_bits

The size of the seed key of the hash algorithm

.. versionadded:: 3.2

Expand Down Expand Up @@ -1081,32 +1122,31 @@ always available.
A :term:`named tuple` that holds information about Python's internal
representation of integers. The attributes are read only.

.. tabularcolumns:: |l|L|

+----------------------------------------+-----------------------------------------------+
| Attribute | Explanation |
+========================================+===============================================+
| :const:`bits_per_digit` | number of bits held in each digit. Python |
| | integers are stored internally in base |
| | ``2**int_info.bits_per_digit`` |
+----------------------------------------+-----------------------------------------------+
| :const:`sizeof_digit` | size in bytes of the C type used to |
| | represent a digit |
+----------------------------------------+-----------------------------------------------+
| :const:`default_max_str_digits` | default value for |
| | :func:`sys.get_int_max_str_digits` when it |
| | is not otherwise explicitly configured. |
+----------------------------------------+-----------------------------------------------+
| :const:`str_digits_check_threshold` | minimum non-zero value for |
| | :func:`sys.set_int_max_str_digits`, |
| | :envvar:`PYTHONINTMAXSTRDIGITS`, or |
| | :option:`-X int_max_str_digits <-X>`. |
+----------------------------------------+-----------------------------------------------+
.. attribute:: int_info.bits_per_digit

The number of bits held in each digit.
Python integers are stored internally in base ``2**int_info.bits_per_digit``.

.. attribute:: int_info.sizeof_digit

The size in bytes of the C type used to represent a digit.

.. attribute:: int_info.default_max_str_digits

The default value for :func:`sys.get_int_max_str_digits`
when it is not otherwise explicitly configured.

.. attribute:: int_info.str_digits_check_threshold

The minimum non-zero value for :func:`sys.set_int_max_str_digits`,
:envvar:`PYTHONINTMAXSTRDIGITS`, or :option:`-X int_max_str_digits <-X>`.

.. versionadded:: 3.1

.. versionchanged:: 3.11
Added ``default_max_str_digits`` and ``str_digits_check_threshold``.

Added :attr:`~int_info.default_max_str_digits` and
:attr:`~int_info.str_digits_check_threshold`.


.. data:: __interactivehook__
Expand Down Expand Up @@ -1533,7 +1573,7 @@ always available.
:file:`Objects/lnotab_notes.txt` for a detailed explanation of how this
works.
Per-line events may be disabled for a frame by setting
:attr:`f_trace_lines` to :const:`False` on that frame.
:attr:`!f_trace_lines` to :const:`False` on that :ref:`frame <frame-objects>`.

``'return'``
A function (or other code block) is about to return. The local trace
Expand All @@ -1551,8 +1591,8 @@ always available.
opcode details). The local trace function is called; *arg* is
``None``; the return value specifies the new local trace function.
Per-opcode events are not emitted by default: they must be explicitly
requested by setting :attr:`f_trace_opcodes` to :const:`True` on the
frame.
requested by setting :attr:`!f_trace_opcodes` to :const:`True` on the
:ref:`frame <frame-objects>`.

Note that as an exception is propagated down the chain of callers, an
``'exception'`` event is generated at each level.
Expand Down Expand Up @@ -1581,8 +1621,8 @@ always available.

.. versionchanged:: 3.7

``'opcode'`` event type added; :attr:`f_trace_lines` and
:attr:`f_trace_opcodes` attributes added to frames
``'opcode'`` event type added; :attr:`!f_trace_lines` and
:attr:`!f_trace_opcodes` attributes added to frames

.. function:: set_asyncgen_hooks(firstiter, finalizer)

Expand Down Expand Up @@ -1739,7 +1779,7 @@ always available.
However, if you are writing a library (and do not control in which
context its code will be executed), be aware that the standard streams
may be replaced with file-like objects like :class:`io.StringIO` which
do not support the :attr:`~io.BufferedIOBase.buffer` attribute.
do not support the :attr:!buffer` attribute.


.. data:: __stdin__
Expand Down Expand Up @@ -1787,29 +1827,28 @@ always available.
A :term:`named tuple` holding information about the thread
implementation.

.. tabularcolumns:: |l|p{0.7\linewidth}|

+------------------+---------------------------------------------------------+
| Attribute | Explanation |
+==================+=========================================================+
| :const:`name` | Name of the thread implementation: |
| | |
| | * ``'nt'``: Windows threads |
| | * ``'pthread'``: POSIX threads |
| | * ``'pthread-stubs'``: stub POSIX threads |
| | (on WebAssembly platforms without threading support) |
| | * ``'solaris'``: Solaris threads |
+------------------+---------------------------------------------------------+
| :const:`lock` | Name of the lock implementation: |
| | |
| | * ``'semaphore'``: a lock uses a semaphore |
| | * ``'mutex+cond'``: a lock uses a mutex |
| | and a condition variable |
| | * ``None`` if this information is unknown |
+------------------+---------------------------------------------------------+
| :const:`version` | Name and version of the thread library. It is a string, |
| | or ``None`` if this information is unknown. |
+------------------+---------------------------------------------------------+
.. attribute:: thread_info.name

The name of the thread implementation:

* ``"nt"``: Windows threads
* ``"pthread"``: POSIX threads
* ``"pthread-stubs"``: stub POSIX threads
(on WebAssembly platforms without threading support)
* ``"solaris"``: Solaris threads

.. attribute:: thread_info.lock

The name of the lock implementation:

* ``"semaphore"``: a lock uses a semaphore
* ``"mutex+cond"``: a lock uses a mutex and a condition variable
* ``None`` if this information is unknown

.. attribute:: thread_info.version

The name and version of the thread library.
It is a string, or ``None`` if this information is unknown.

.. versionadded:: 3.3

Expand Down
2 changes: 1 addition & 1 deletion Doc/library/textwrap.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ functions should be good enough; otherwise, you should use an instance of
First the whitespace in *text* is collapsed (all whitespace is replaced by
single spaces). If the result fits in the *width*, it is returned.
Otherwise, enough words are dropped from the end so that the remaining words
plus the :attr:`.placeholder` fit within :attr:`.width`::
plus the *placeholder* fit within *width*::

>>> textwrap.shorten("Hello world!", width=12)
'Hello world!'
Expand Down
1 change: 0 additions & 1 deletion Doc/tools/.nitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,6 @@ Doc/library/ssl.rst
Doc/library/stdtypes.rst
Doc/library/string.rst
Doc/library/subprocess.rst
Doc/library/sys.rst
Doc/library/sys_path_init.rst
Doc/library/syslog.rst
Doc/library/tarfile.rst
Expand Down

0 comments on commit 29fa7af

Please sign in to comment.