GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing github.com — gh-141984: Reword and reorganize Subscription (and Slicing) docs (GH-… · thunder-coding/cpython@24d100e

File tree

Expand file treeCollapse file tree

Open diff view settings

Filter options

Doc
- glossary.rst
- library
  - functions.rst
- reference

Expand file treeCollapse file tree

Open diff view settings

Collapse file

`‎Doc/glossary.rst‎`

Copy file name to clipboardExpand all lines: Doc/glossary.rst

+29-4Lines changed: 29 additions & 4 deletions

Display the source diff
Display the rich diff

Original file line number	Diff line number	Diff line change
`@@ -786,6 +786,19 @@ Glossary`
`786`	`786`	`An object that both finds and loads a module; both a`
`787`	`787`	:term:`finder` and :term:`loader` object.
`788`	`788`
	`789`	`+ index`
	`790`	`+ A numeric value that represents the position of an element in`
	`791`	+ a :term:`sequence`.
	`792`	`+`
	`793`	`+ In Python, indexing starts at zero.`
	`794`	+ For example, ``things[0]`` names the first element of ``things``;
	`795`	+ ``things[1]`` names the second one.
	`796`	`+`
	`797`	`+ In some contexts, Python allows negative indexes for counting from the`
	`798`	+ end of a sequence, and indexing using :term:`slices <slice>`.
	`799`	`+`
	`800`	+ See also :term:`subscript`.
	`801`	`+`
`789`	`802`	`interactive`
`790`	`803`	`Python has an interactive interpreter which means you can enter`
`791`	`804`	`statements and expressions at the interpreter prompt, immediately`
`@@ -863,6 +876,9 @@ Glossary`
`863`	`876`	CPython does not guarantee :term:`thread-safe` behavior of iterator
`864`	`877`	`operations.`
`865`	`878`
	`879`	`+ key`
	`880`	+ A value that identifies an entry in a :term:`mapping`.
	`881`	+ See also :term:`subscript`.
`866`	`882`
`867`	`883`	`key function`
`868`	`884`	`A key function or collation function is a callable that returns a value`
`@@ -1417,10 +1433,11 @@ Glossary`
`1417`	`1433`	`chosen based on the type of a single argument.`
`1418`	`1434`
`1419`	`1435`	`slice`
`1420`		- An object usually containing a portion of a :term:`sequence`. A slice is
`1421`		- created using the subscript notation, ``[]`` with colons between numbers
`1422`		- when several are given, such as in ``variable_name[1:3:5]``. The bracket
`1423`		- (subscript) notation uses :class:`slice` objects internally.
	`1436`	+ An object of type :class:`slice`, used to describe a portion of
	`1437`	+ a :term:`sequence`.
	`1438`	+ A slice object is created when using the :ref:`slicing <slicings>` form
	`1439`	+ of :ref:`subscript notation <subscriptions>`, with colons inside square
	`1440`	+ brackets, such as in ``variable_name[1:3:5]``.
`1424`	`1441`
`1425`	`1442`	`soft deprecated`
`1426`	`1443`	`A soft deprecated API should not be used in new code,`
`@@ -1478,6 +1495,14 @@ Glossary`
`1478`	`1495`
`1479`	`1496`	See also :term:`borrowed reference`.
`1480`	`1497`
	`1498`	`+ subscript`
	`1499`	`+ The expression in square brackets of a`
	`1500`	+ :ref:`subscription expression <subscriptions>`, for example,
	`1501`	+ the ``3`` in ``items[3]``.
	`1502`	`+ Usually used to select an element of a container.`
	`1503`	+ Also called a :term:`key` when subscripting a :term:`mapping`,
	`1504`	+ or an :term:`index` when subscripting a :term:`sequence`.
	`1505`	`+`
`1481`	`1506`	`synchronization primitive`
`1482`	`1507`	`A basic building block for coordinating (synchronizing) the execution of`
`1483`	`1508`	multiple threads to ensure :term:`thread-safe` access to shared resources.

Collapse file

`‎Doc/library/functions.rst‎`

Copy file name to clipboardExpand all lines: Doc/library/functions.rst

+10-10Lines changed: 10 additions & 10 deletions

Display the source diff
Display the rich diff

Original file line number	Diff line number	Diff line change
`@@ -1824,19 +1824,19 @@ are always available. They are listed here in alphabetical order.`
`1824`	`1824`	``range(start, stop, step)``. The start and step arguments default to
`1825`	`1825`	``None``.
`1826`	`1826`
`1827`		- Slice objects have read-only data attributes :attr:`!start`,
`1828`		- :attr:`!stop`, and :attr:`!step` which merely return the argument
`1829`		`- values (or their default). They have no other explicit functionality;`
`1830`		`- however, they are used by NumPy and other third-party packages.`
	`1827`	+ Slice objects are also generated when :ref:`slicing syntax <slicings>`
	`1828`	+ is used. For example: ``a[start:stop:step]`` or ``a[start:stop, i]``.
	`1829`	`+`
	`1830`	+ See :func:`itertools.islice` for an alternate version that returns an
	`1831`	+ :term:`iterator`.
`1831`	`1832`
`1832`	`1833`	`.. attribute:: slice.start`
`1833`		`- .. attribute:: slice.stop`
`1834`		`- .. attribute:: slice.step`
	`1834`	`+ slice.stop`
	`1835`	`+ slice.step`
`1835`	`1836`
`1836`		`- Slice objects are also generated when extended indexing syntax is used. For`
`1837`		- example: ``a[start:stop:step]`` or ``a[start:stop, i]``. See
`1838`		- :func:`itertools.islice` for an alternate version that returns an
`1839`		- :term:`iterator`.
	`1837`	`+ These read-only attributes are set to the argument values`
	`1838`	`+ (or their default). They have no other explicit functionality;`
	`1839`	`+ however, they are used by NumPy and other third-party packages.`
`1840`	`1840`
`1841`	`1841`	`.. versionchanged:: 3.12`
`1842`	`1842`	Slice objects are now :term:`hashable` (provided :attr:`~slice.start`,

Collapse file

`‎Doc/reference/datamodel.rst‎`

Copy file name to clipboardExpand all lines: Doc/reference/datamodel.rst

+60-28Lines changed: 60 additions & 28 deletions

Display the source diff
Display the rich diff

Original file line number	Diff line number	Diff line change
`@@ -290,6 +290,7 @@ floating-point numbers. The same caveats apply as for floating-point numbers.`
`290`	`290`	The real and imaginary parts of a complex number ``z`` can be retrieved through
`291`	`291`	the read-only attributes ``z.real`` and ``z.imag``.
`292`	`292`
	`293`	`+.. _datamodel-sequences:`
`293`	`294`
`294`	`295`	`Sequences`
`295`	`296`	`---------`
`@@ -309,12 +310,25 @@ including built-in sequences, interpret negative subscripts by adding the`
`309`	`310`	sequence length. For example, ``a[-2]`` equals ``a[n-2]``, the second to last
`310`	`311`	item of sequence a with length ``n``.
`311`	`312`
`312`		`-.. index:: single: slicing`
	`313`	`+The resulting value must be a nonnegative integer less than the number of items`
	`314`	+in the sequence. If it is not, an :exc:`IndexError` is raised.
`313`	`315`
`314`		-Sequences also support slicing: ``a[i:j]`` selects all items with index k such
`315`		-that i ``<=`` k ``<`` j. When used as an expression, a slice is a
`316`		`-sequence of the same type. The comment above about negative indexes also applies`
	`316`	`+.. index::`
	`317`	`+ single: slicing`
	`318`	`+ single: start (slice object attribute)`
	`319`	`+ single: stop (slice object attribute)`
	`320`	`+ single: step (slice object attribute)`
	`321`	`+`
	`322`	+Sequences also support slicing: ``a[start:stop]`` selects all items with index k such
	`323`	+that start ``<=`` k ``<`` stop. When used as an expression, a slice is a
	`324`	`+sequence of the same type. The comment above about negative subscripts also applies`
`317`	`325`	`to negative slice positions.`
	`326`	`+Note that no error is raised if a slice position is less than zero or larger`
	`327`	`+than the length of the sequence.`
	`328`	`+`
	`329`	+If start is missing or :data:`None`, slicing behaves as if start was zero.
	`330`	+If stop is missing or ``None``, slicing behaves as if stop was equal to
	`331`	`+the length of the sequence.`
`318`	`332`
`319`	`333`	`Some sequences also support "extended slicing" with a third "step" parameter:`
`320`	`334`	``a[i:j:k]`` selects all items of a with index x where ``x = i + nk``, n*
`@@ -345,17 +359,22 @@ Strings`
`345`	`359`	`pair: built-in function; chr`
`346`	`360`	`pair: built-in function; ord`
`347`	`361`	`single: character`
`348`		`- single: integer`
	`362`	`+ pair: string; item`
`349`	`363`	`single: Unicode`
`350`	`364`
`351`		`- A string is a sequence of values that represent Unicode code points.`
`352`		- All the code points in the range ``U+0000 - U+10FFFF`` can be
`353`		- represented in a string. Python doesn't have a :c:expr:`char` type;
`354`		`- instead, every code point in the string is represented as a string`
`355`		- object with length ``1``. The built-in function :func:`ord`
	`365`	+ A string (:class:`str`) is a sequence of values that represent
	`366`	+ :dfn:`characters`, or more formally, Unicode code points.
	`367`	+ All the code points in the range ``0`` to ``0x10FFFF`` can be
	`368`	`+ represented in a string.`
	`369`	`+`
	`370`	`+ Python doesn't have a dedicated character type.`
	`371`	`+ Instead, every code point in the string is represented as a string`
	`372`	+ object with length ``1``.
	`373`	`+`
	`374`	+ The built-in function :func:`ord`
`356`	`375`	`converts a code point from its string form to an integer in the`
`357`		- range ``0 - 10FFFF``; :func:`chr` converts an integer in the range
`358`		- ``0 - 10FFFF`` to the corresponding length ``1`` string object.
	`376`	+ range ``0`` to ``0x10FFFF``; :func:`chr` converts an integer in the range
	`377`	+ ``0`` to ``0x10FFFF`` to the corresponding length ``1`` string object.
`359`	`378`	:meth:`str.encode` can be used to convert a :class:`str` to
`360`	`379`	:class:`bytes` using the given text encoding, and
`361`	`380`	:meth:`bytes.decode` can be used to achieve the opposite.
`@@ -366,7 +385,7 @@ Tuples`
`366`	`385`	`pair: singleton; tuple`
`367`	`386`	`pair: empty; tuple`
`368`	`387`
`369`		`- The items of a tuple are arbitrary Python objects. Tuples of two or`
	`388`	+ The items of a :class:`tuple` are arbitrary Python objects. Tuples of two or
`370`	`389`	`more items are formed by comma-separated lists of expressions. A tuple`
`371`	`390`	`of one item (a 'singleton') can be formed by affixing a comma to an`
`372`	`391`	`expression (an expression by itself does not create a tuple, since`
`@@ -376,7 +395,7 @@ Tuples`
`376`	`395`	`Bytes`
`377`	`396`	`.. index:: bytes, byte`
`378`	`397`
`379`		`- A bytes object is an immutable array. The items are 8-bit bytes,`
	`398`	+ A :class:`bytes` object is an immutable array. The items are 8-bit bytes,
`380`	`399`	`represented by integers in the range 0 <= x < 256. Bytes literals`
`381`	`400`	(like ``b'abc'``) and the built-in :func:`bytes` constructor
`382`	`401`	`can be used to create bytes objects. Also, bytes objects can be`
`@@ -461,6 +480,8 @@ Frozen sets`
`461`	`480`	`a dictionary key.`
`462`	`481`
`463`	`482`
	`483`	`+.. _datamodel-mappings:`
	`484`	`+`
`464`	`485`	`Mappings`
`465`	`486`	`--------`
`466`	`487`
`@@ -3217,28 +3238,39 @@ through the object's keys; for sequences, it should iterate through the values.`
`3217`	`3238`	and so forth. Missing slice items are always filled in with ``None``.
`3218`	`3239`
`3219`	`3240`
`3220`		`-.. method:: object.__getitem__(self, key)`
	`3241`	`+.. method:: object.__getitem__(self, subscript)`
	`3242`	`+`
	`3243`	+ Called to implement subscription, that is, ``self[subscript]``.
	`3244`	+ See :ref:`subscriptions` for details on the syntax.
	`3245`	`+`
	`3246`	`+ There are two types of built-in objects that support subscription`
	`3247`	+ via :meth:`!__getitem__`:
	`3248`	`+`
	`3249`	`+ - sequences, where subscript (also called`
	`3250`	+ :term:`index`) should be an integer or a :class:`slice` object.
	`3251`	+ See the :ref:`sequence documentation <datamodel-sequences>` for the expected
	`3252`	+ behavior, including handling :class:`slice` objects and negative indices.
	`3253`	+ - mappings, where subscript is also called the :term:`key`.
	`3254`	+ See :ref:`mapping documentation <datamodel-mappings>` for the expected
	`3255`	`+ behavior.`
`3221`	`3256`
`3222`		- Called to implement evaluation of ``self[key]``. For :term:`sequence` types,
`3223`		`- the accepted keys should be integers. Optionally, they may support`
`3224`		- :class:`slice` objects as well. Negative index support is also optional.
`3225`		`- If key is`
`3226`		- of an inappropriate type, :exc:`TypeError` may be raised; if key is a value
`3227`		`- outside the set of indexes for the sequence (after any special`
`3228`		- interpretation of negative values), :exc:`IndexError` should be raised. For
`3229`		- :term:`mapping` types, if key is missing (not in the container),
`3230`		- :exc:`KeyError` should be raised.
	`3257`	+ If subscript is of an inappropriate type, :meth:`!__getitem__`
	`3258`	+ should raise :exc:`TypeError`.
	`3259`	+ If subscript has an inappropriate value, :meth:`!__getitem__`
	`3260`	+ should raise an :exc:`LookupError` or one of its subclasses
	`3261`	+ (:exc:`IndexError` for sequences; :exc:`KeyError` for mappings).
`3231`	`3262`
`3232`	`3263`	`.. note::`
`3233`	`3264`
`3234`		- :keyword:`for` loops expect that an :exc:`IndexError` will be raised for
`3235`		`- illegal indexes to allow proper detection of the end of the sequence.`
	`3265`	+ The sequence iteration protocol (used, for example, in :keyword:`for`
	`3266`	+ loops), expects that an :exc:`IndexError` will be raised for illegal
	`3267`	`+ indexes to allow proper detection of the end of a sequence.`
`3236`	`3268`
`3237`	`3269`	`.. note::`
`3238`	`3270`
`3239`		- When :ref:`subscripting<subscriptions>` a class, the special
	`3271`	+ When :ref:`subscripting <subscriptions>` a class, the special
`3240`	`3272`	class method :meth:`~object.__class_getitem__` may be called instead of
`3241`		- ``__getitem__()``. See :ref:`classgetitem-versus-getitem` for more
	`3273`	+ :meth:`!__getitem__`. See :ref:`classgetitem-versus-getitem` for more
`3242`	`3274`	`details.`
`3243`	`3275`
`3244`	`3276`

0 commit comments

Comments

0 (0)

You are visitor 01402520 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.