mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-23 08:53:45 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

Docs: Fix Sphinx warnings in sys.rst (#108106)

Browse source 
- 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>
This commit is contained in:
Erlend E. Aasland 2023-08-20 13:09:33 +02:00 • committed by GitHub
parent beffb30dc7
commit 29fa7afef9
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 150 additions and 112 deletions
Download patch file Download diff file Expand all files Collapse all files

259
Doc/library/sys.rst
View file

@ -333,23 +333,21 @@ always available.
*wasm32-emscripten* platform. The named tuple is provisional and may change *wasm32-emscripten* platform. The named tuple is provisional and may change
in the future. in the future.
.. tabularcolumns:: |l|L| .. attribute:: _emscripten_info.emscripten_version
+-----------------------------+----------------------------------------------+ Emscripten version as tuple of ints (major, minor, micro), e.g. ``(3, 1, 8)``.
| Attribute | Explanation |
+=============================+==============================================+ .. attribute:: _emscripten_info.runtime
| :const:`emscripten_version` | Emscripten version as tuple of ints |
| | (major, minor, micro), e.g. ``(3, 1, 8)``. | Runtime string, e.g. browser user agent, ``'Node.js v14.18.2'``, or ``'UNKNOWN'``.
+-----------------------------+----------------------------------------------+
| :const:`runtime` | Runtime string, e.g. browser user agent, | .. attribute:: _emscripten_info.pthreads
| | ``'Node.js v14.18.2'``, or ``'UNKNOWN'``. |
+-----------------------------+----------------------------------------------+ ``True`` if Python is compiled with Emscripten pthreads support.
| :const:`pthreads` | ``True`` if Python is compiled with |
| | Emscripten pthreads support. | .. attribute:: _emscripten_info.shared_memory
+-----------------------------+----------------------------------------------+
| :const:`shared_memory` | ``True`` if Python is compiled with shared | ``True`` if Python is compiled with shared memory support.
| | memory support. |
+-----------------------------+----------------------------------------------+
.. availability:: Emscripten. .. availability:: Emscripten.
@ -515,28 +513,62 @@ always available.
The :term:`named tuple` *flags* exposes the status of command line The :term:`named tuple` *flags* exposes the status of command line
flags. The attributes are read only. flags. The attributes are read only.
============================== ============================================================================================================== .. list-table::
attribute flag
============================== ============================================================================================================== * - .. attribute:: flags.debug
:const:`debug` :option:`-d` - :option:`-d`
:const:`inspect` :option:`-i`
:const:`interactive` :option:`-i` * - .. attribute:: flags.inspect
:const:`isolated` :option:`-I` - :option:`-i`
:const:`optimize` :option:`-O` or :option:`-OO`
:const:`dont_write_bytecode` :option:`-B` * - .. attribute:: flags.interactive
:const:`no_user_site` :option:`-s` - :option:`-i`
:const:`no_site` :option:`-S`
:const:`ignore_environment` :option:`-E` * - .. attribute:: flags.isolated
:const:`verbose` :option:`-v` - :option:`-I`
:const:`bytes_warning` :option:`-b`
:const:`quiet` :option:`-q` * - .. attribute:: flags.optimize
:const:`hash_randomization` :option:`-R` - :option:`-O` or :option:`-OO`
:const:`dev_mode` :option:`-X dev <-X>` (:ref:`Python Development Mode <devmode>`)
:const:`utf8_mode` :option:`-X utf8 <-X>` * - .. attribute:: flags.dont_write_bytecode
:const:`safe_path` :option:`-P` - :option:`-B`
: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>` * - .. 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 .. versionchanged:: 3.2
Added ``quiet`` attribute for the new :option:`-q` flag. Added ``quiet`` attribute for the new :option:`-q` flag.
@ -923,8 +955,8 @@ always available.
| | a domain controller. | | | a domain controller. |
+---------------------------------------+---------------------------------+ +---------------------------------------+---------------------------------+
This function wraps the Win32 :c:func:`GetVersionEx` function; see the This function wraps the Win32 :c:func:`!GetVersionEx` function; see the
Microsoft documentation on :c:func:`OSVERSIONINFOEX` for more information Microsoft documentation on :c:func:`!OSVERSIONINFOEX` for more information
about these fields. about these fields.
*platform_version* returns the major version, minor version and *platform_version* returns the major version, minor version and
@ -982,28 +1014,37 @@ always available.
implementation. For more details about hashing of numeric types, see implementation. For more details about hashing of numeric types, see
:ref:`numeric-hash`. :ref:`numeric-hash`.
+---------------------+--------------------------------------------------+ .. attribute:: hash_info.width
| 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 |
+---------------------+--------------------------------------------------+
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 .. versionadded:: 3.2
@ -1081,32 +1122,31 @@ always available.
A :term:`named tuple` that holds information about Python's internal A :term:`named tuple` that holds information about Python's internal
representation of integers. The attributes are read only. representation of integers. The attributes are read only.
.. tabularcolumns:: |l|L| .. attribute:: int_info.bits_per_digit
+----------------------------------------+-----------------------------------------------+ The number of bits held in each digit.
| Attribute | Explanation | Python integers are stored internally in base ``2**int_info.bits_per_digit``.
+========================================+===============================================+
| :const:`bits_per_digit` | number of bits held in each digit. Python | .. attribute:: int_info.sizeof_digit
| | integers are stored internally in base |
| | ``2**int_info.bits_per_digit`` | The size in bytes of the C type used to represent a digit.
+----------------------------------------+-----------------------------------------------+
| :const:`sizeof_digit` | size in bytes of the C type used to | .. attribute:: int_info.default_max_str_digits
| | represent a digit |
+----------------------------------------+-----------------------------------------------+ The default value for :func:`sys.get_int_max_str_digits`
| :const:`default_max_str_digits` | default value for | when it is not otherwise explicitly configured.
| | :func:`sys.get_int_max_str_digits` when it |
| | is not otherwise explicitly configured. | .. attribute:: int_info.str_digits_check_threshold
+----------------------------------------+-----------------------------------------------+
| :const:`str_digits_check_threshold` | minimum non-zero value for | The minimum non-zero value for :func:`sys.set_int_max_str_digits`,
| | :func:`sys.set_int_max_str_digits`, | :envvar:`PYTHONINTMAXSTRDIGITS`, or :option:`-X int_max_str_digits <-X>`.
| | :envvar:`PYTHONINTMAXSTRDIGITS`, or |
| | :option:`-X int_max_str_digits <-X>`. |
+----------------------------------------+-----------------------------------------------+
.. versionadded:: 3.1 .. versionadded:: 3.1
.. versionchanged:: 3.11 .. 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__ .. data:: __interactivehook__
@ -1533,7 +1573,7 @@ always available.
:file:`Objects/lnotab_notes.txt` for a detailed explanation of how this :file:`Objects/lnotab_notes.txt` for a detailed explanation of how this
works. works.
Per-line events may be disabled for a frame by setting 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'`` ``'return'``
A function (or other code block) is about to return. The local trace A function (or other code block) is about to return. The local trace
@ -1551,8 +1591,8 @@ always available.
opcode details). The local trace function is called; *arg* is opcode details). The local trace function is called; *arg* is
``None``; the return value specifies the new local trace function. ``None``; the return value specifies the new local trace function.
Per-opcode events are not emitted by default: they must be explicitly Per-opcode events are not emitted by default: they must be explicitly
requested by setting :attr:`f_trace_opcodes` to :const:`True` on the requested by setting :attr:`!f_trace_opcodes` to :const:`True` on the
frame. :ref:`frame <frame-objects>`.
Note that as an exception is propagated down the chain of callers, an Note that as an exception is propagated down the chain of callers, an
``'exception'`` event is generated at each level. ``'exception'`` event is generated at each level.
@ -1581,8 +1621,8 @@ always available.
.. versionchanged:: 3.7 .. versionchanged:: 3.7
``'opcode'`` event type added; :attr:`f_trace_lines` and ``'opcode'`` event type added; :attr:`!f_trace_lines` and
:attr:`f_trace_opcodes` attributes added to frames :attr:`!f_trace_opcodes` attributes added to frames
.. function:: set_asyncgen_hooks(firstiter, finalizer) .. function:: set_asyncgen_hooks(firstiter, finalizer)
@ -1739,7 +1779,7 @@ always available.
However, if you are writing a library (and do not control in which 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 context its code will be executed), be aware that the standard streams
may be replaced with file-like objects like :class:`io.StringIO` which 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__ .. data:: __stdin__
@ -1787,29 +1827,28 @@ always available.
A :term:`named tuple` holding information about the thread A :term:`named tuple` holding information about the thread
implementation. implementation.
.. tabularcolumns:: |l|p{0.7\linewidth}| .. attribute:: thread_info.name
+------------------+---------------------------------------------------------+ The name of the thread implementation:
| Attribute | Explanation |
+==================+=========================================================+ * ``"nt"``: Windows threads
| :const:`name` | Name of the thread implementation: | * ``"pthread"``: POSIX threads
| | | * ``"pthread-stubs"``: stub POSIX threads
| | * ``'nt'``: Windows threads | (on WebAssembly platforms without threading support)
| | * ``'pthread'``: POSIX threads | * ``"solaris"``: Solaris threads
| | * ``'pthread-stubs'``: stub POSIX threads |
| | (on WebAssembly platforms without threading support) | .. attribute:: thread_info.lock
| | * ``'solaris'``: Solaris threads |
+------------------+---------------------------------------------------------+ The name of the lock implementation:
| :const:`lock` | Name of the lock implementation: |
| | | * ``"semaphore"``: a lock uses a semaphore
| | * ``'semaphore'``: a lock uses a semaphore | * ``"mutex+cond"``: a lock uses a mutex and a condition variable
| | * ``'mutex+cond'``: a lock uses a mutex | * ``None`` if this information is unknown
| | and a condition variable |
| | * ``None`` if this information is unknown | .. attribute:: thread_info.version
+------------------+---------------------------------------------------------+
| :const:`version` | Name and version of the thread library. It is a string, | The name and version of the thread library.
| | or ``None`` if this information is unknown. | It is a string, or ``None`` if this information is unknown.
+------------------+---------------------------------------------------------+
.. versionadded:: 3.3 .. versionadded:: 3.3

2
Doc/library/textwrap.rst
View file

@ -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 First the whitespace in *text* is collapsed (all whitespace is replaced by
single spaces). If the result fits in the *width*, it is returned. 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 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) >>> textwrap.shorten("Hello world!", width=12)
'Hello world!' 'Hello world!'

1
Doc/tools/.nitignore
View file

@ -127,7 +127,6 @@ Doc/library/ssl.rst
Doc/library/stdtypes.rst Doc/library/stdtypes.rst
Doc/library/string.rst Doc/library/string.rst
Doc/library/subprocess.rst Doc/library/subprocess.rst
Doc/library/sys.rst
Doc/library/sys_path_init.rst Doc/library/sys_path_init.rst
Doc/library/syslog.rst Doc/library/syslog.rst
Doc/library/tarfile.rst Doc/library/tarfile.rst