must be of integer types, and *y* must be non-negative.
- .. function:: print([object, ...], *, sep=' ', end='\\n', file=sys.stdout, flush=False)
-.. function:: print(*objects, sep=' ', end='\\n', file=sys.stdout)
++.. function:: print(*objects, sep=' ', end='\\n', file=sys.stdout, flush=False)
- Print *object*\(s) to the stream *file*, separated by *sep* and followed by
+ Print *objects* to the stream *file*, separated by *sep* and followed by
*end*. *sep*, *end* and *file*, if present, must be given as keyword
arguments.
``fdel`` corresponding to the constructor arguments.
-.. XXX does accept objects with __index__ too
+.. _func-range:
- .. function:: range([start,] stop[, step])
+ .. function:: range(stop)
+ range(start, stop[, step])
+ :noindex:
- This is a versatile function to create iterables yielding arithmetic
- progressions. It is most often used in :keyword:`for` loops. The arguments
- must be integers. If the *step* argument is omitted, it defaults to ``1``.
- If the *start* argument is omitted, it defaults to ``0``. The full form
- returns an iterable of integers ``[start, start + step, start + 2 * step,
- ...]``. If *step* is positive, the last element is the largest ``start + i *
- step`` less than *stop*; if *step* is negative, the last element is the
- smallest ``start + i * step`` greater than *stop*. *step* must not be zero
- (or else :exc:`ValueError` is raised). Example:
-
- >>> list(range(10))
- [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
- >>> list(range(1, 11))
- [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
- >>> list(range(0, 30, 5))
- [0, 5, 10, 15, 20, 25]
- >>> list(range(0, 10, 3))
- [0, 3, 6, 9]
- >>> list(range(0, -10, -1))
- [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
- >>> list(range(0))
- []
- >>> list(range(1, 0))
- []
-
- Range objects implement the :class:`collections.Sequence` ABC, and provide
- features such as containment tests, element index lookup, slicing and
- support for negative indices (see :ref:`typesseq`):
-
- >>> r = range(0, 20, 2)
- >>> r
- range(0, 20, 2)
- >>> 11 in r
- False
- >>> 10 in r
- True
- >>> r.index(10)
- 5
- >>> r[5]
- 10
- >>> r[:5]
- range(0, 10, 2)
- >>> r[-1]
- 18
-
- Ranges containing absolute values larger than :data:`sys.maxsize` are permitted
- but some features (such as :func:`len`) will raise :exc:`OverflowError`.
-
- .. versionchanged:: 3.2
- Implement the Sequence ABC.
- Support slicing and negative indices.
- Test integers for membership in constant time instead of iterating
- through all items.
+ Rather than being a function, :class:`range` is actually an immutable
+ sequence type, as documented in :ref:`typesseq`.
.. function:: repr(object)
onwards is removed. Also, all tabs are expanded to spaces.
- .. method:: Signature.replace([parameters], *, [return_annotation])
+.. _inspect-signature-object:
+
+Introspecting callables with the Signature object
+-------------------------------------------------
+
+.. versionadded:: 3.3
+
+The Signature object represents the call signature of a callable object and its
+return annotation. To retrieve a Signature object, use the :func:`signature`
+function.
+
+.. function:: signature(callable)
+
+ Return a :class:`Signature` object for the given ``callable``::
+
+ >>> from inspect import signature
+ >>> def foo(a, *, b:int, **kwargs):
+ ... pass
+
+ >>> sig = signature(foo)
+
+ >>> str(sig)
+ '(a, *, b:int, **kwargs)'
+
+ >>> str(sig.parameters['b'])
+ 'b:int'
+
+ >>> sig.parameters['b'].annotation
+ <class 'int'>
+
+ Accepts a wide range of python callables, from plain functions and classes to
+ :func:`functools.partial` objects.
+
+ .. note::
+
+ Some callables may not be introspectable in certain implementations of
+ Python. For example, in CPython, built-in functions defined in C provide
+ no metadata about their arguments.
+
+
+.. class:: Signature
+
+ A Signature object represents the call signature of a function and its return
+ annotation. For each parameter accepted by the function it stores a
+ :class:`Parameter` object in its :attr:`parameters` collection.
+
+ Signature objects are *immutable*. Use :meth:`Signature.replace` to make a
+ modified copy.
+
+ .. attribute:: Signature.empty
+
+ A special class-level marker to specify absence of a return annotation.
+
+ .. attribute:: Signature.parameters
+
+ An ordered mapping of parameters' names to the corresponding
+ :class:`Parameter` objects.
+
+ .. attribute:: Signature.return_annotation
+
+ The "return" annotation for the callable. If the callable has no "return"
+ annotation, this attribute is set to :attr:`Signature.empty`.
+
+ .. method:: Signature.bind(*args, **kwargs)
+
+ Create a mapping from positional and keyword arguments to parameters.
+ Returns :class:`BoundArguments` if ``*args`` and ``**kwargs`` match the
+ signature, or raises a :exc:`TypeError`.
+
+ .. method:: Signature.bind_partial(*args, **kwargs)
+
+ Works the same way as :meth:`Signature.bind`, but allows the omission of
+ some required arguments (mimics :func:`functools.partial` behavior.)
+ Returns :class:`BoundArguments`, or raises a :exc:`TypeError` if the
+ passed arguments do not match the signature.
+
- .. method:: Parameter.replace(*, [name], [kind], [default], [annotation])
++ .. method:: Signature.replace(*[, parameters][, return_annotation])
+
+ Create a new Signature instance based on the instance replace was invoked
+ on. It is possible to pass different ``parameters`` and/or
+ ``return_annotation`` to override the corresponding properties of the base
+ signature. To remove return_annotation from the copied Signature, pass in
+ :attr:`Signature.empty`.
+
+ ::
+
+ >>> def test(a, b):
+ ... pass
+ >>> sig = signature(test)
+ >>> new_sig = sig.replace(return_annotation="new return anno")
+ >>> str(new_sig)
+ "(a, b) -> 'new return anno'"
+
+
+.. class:: Parameter
+
+ Parameter objects are *immutable*. Instead of modifying a Parameter object,
+ you can use :meth:`Parameter.replace` to create a modified copy.
+
+ .. attribute:: Parameter.empty
+
+ A special class-level marker to specify absence of default values and
+ annotations.
+
+ .. attribute:: Parameter.name
+
+ The name of the parameter as a string. Must be a valid python identifier
+ name (with the exception of ``POSITIONAL_ONLY`` parameters, which can have
+ it set to ``None``).
+
+ .. attribute:: Parameter.default
+
+ The default value for the parameter. If the parameter has no default
+ value, this attribute is set to :attr:`Parameter.empty`.
+
+ .. attribute:: Parameter.annotation
+
+ The annotation for the parameter. If the parameter has no annotation,
+ this attribute is set to :attr:`Parameter.empty`.
+
+ .. attribute:: Parameter.kind
+
+ Describes how argument values are bound to the parameter. Possible values
+ (accessible via :class:`Parameter`, like ``Parameter.KEYWORD_ONLY``):
+
+ +------------------------+----------------------------------------------+
+ | Name | Meaning |
+ +========================+==============================================+
+ | *POSITIONAL_ONLY* | Value must be supplied as a positional |
+ | | argument. |
+ | | |
+ | | Python has no explicit syntax for defining |
+ | | positional-only parameters, but many built-in|
+ | | and extension module functions (especially |
+ | | those that accept only one or two parameters)|
+ | | accept them. |
+ +------------------------+----------------------------------------------+
+ | *POSITIONAL_OR_KEYWORD*| Value may be supplied as either a keyword or |
+ | | positional argument (this is the standard |
+ | | binding behaviour for functions implemented |
+ | | in Python.) |
+ +------------------------+----------------------------------------------+
+ | *VAR_POSITIONAL* | A tuple of positional arguments that aren't |
+ | | bound to any other parameter. This |
+ | | corresponds to a ``*args`` parameter in a |
+ | | Python function definition. |
+ +------------------------+----------------------------------------------+
+ | *KEYWORD_ONLY* | Value must be supplied as a keyword argument.|
+ | | Keyword only parameters are those which |
+ | | appear after a ``*`` or ``*args`` entry in a |
+ | | Python function definition. |
+ +------------------------+----------------------------------------------+
+ | *VAR_KEYWORD* | A dict of keyword arguments that aren't bound|
+ | | to any other parameter. This corresponds to a|
+ | | ``**kwargs`` parameter in a Python function |
+ | | definition. |
+ +------------------------+----------------------------------------------+
+
+ Example: print all keyword-only arguments without default values::
+
+ >>> def foo(a, b, *, c, d=10):
+ ... pass
+
+ >>> sig = signature(foo)
+ >>> for param in sig.parameters.values():
+ ... if (param.kind == param.KEYWORD_ONLY and
+ ... param.default is param.empty):
+ ... print('Parameter:', param)
+ Parameter: c
+
++ .. method:: Parameter.replace(*[, name][, kind][, default][, annotation])
+
+ Create a new Parameter instance based on the instance replaced was invoked
+ on. To override a :class:`Parameter` attribute, pass the corresponding
+ argument. To remove a default value or/and an annotation from a
+ Parameter, pass :attr:`Parameter.empty`.
+
+ ::
+
+ >>> from inspect import Parameter
+ >>> param = Parameter('foo', Parameter.KEYWORD_ONLY, default=42)
+ >>> str(param)
+ 'foo=42'
+
+ >>> str(param.replace()) # Will create a shallow copy of 'param'
+ 'foo=42'
+
+ >>> str(param.replace(default=Parameter.empty, annotation='spam'))
+ "foo:'spam'"
+
+
+.. class:: BoundArguments
+
+ Result of a :meth:`Signature.bind` or :meth:`Signature.bind_partial` call.
+ Holds the mapping of arguments to the function's parameters.
+
+ .. attribute:: BoundArguments.arguments
+
+ An ordered, mutable mapping (:class:`collections.OrderedDict`) of
+ parameters' names to arguments' values. Contains only explicitly bound
+ arguments. Changes in :attr:`arguments` will reflect in :attr:`args` and
+ :attr:`kwargs`.
+
+ Should be used in conjunction with :attr:`Signature.parameters` for any
+ argument processing purposes.
+
+ .. note::
+
+ Arguments for which :meth:`Signature.bind` or
+ :meth:`Signature.bind_partial` relied on a default value are skipped.
+ However, if needed, it is easy to include them.
+
+ ::
+
+ >>> def foo(a, b=10):
+ ... pass
+
+ >>> sig = signature(foo)
+ >>> ba = sig.bind(5)
+
+ >>> ba.args, ba.kwargs
+ ((5,), {})
+
+ >>> for param in sig.parameters.values():
+ ... if param.name not in ba.arguments:
+ ... ba.arguments[param.name] = param.default
+
+ >>> ba.args, ba.kwargs
+ ((5, 10), {})
+
+
+ .. attribute:: BoundArguments.args
+
+ A tuple of positional arguments values. Dynamically computed from the
+ :attr:`arguments` attribute.
+
+ .. attribute:: BoundArguments.kwargs
+
+ A dict of keyword arguments values. Dynamically computed from the
+ :attr:`arguments` attribute.
+
+ The :attr:`args` and :attr:`kwargs` properties can be used to invoke
+ functions::
+
+ def test(a, *, b):
+ ...
+
+ sig = signature(test)
+ ba = sig.bind(10, b=20)
+ test(*ba.args, **ba.kwargs)
+
+
+.. seealso::
+
+ :pep:`362` - Function Signature Object.
+ The detailed specification, implementation details and examples.
+
+
.. _inspect-classes-functions:
Classes and functions
If *k* is ``None``, it is treated like ``1``.
(6)
- Concatenating immutable strings always results in a new object. This means
- that building up a string by repeated concatenation will have a quadratic
- runtime cost in the total string length. To get a linear runtime cost,
- you must switch to one of the alternatives below:
+ Concatenating immutable sequences always results in a new object. This
+ means that building up a sequence by repeated concatenation will have a
+ quadratic runtime cost in the total sequence length. To get a linear
+ runtime cost, you must switch to one of the alternatives below:
* if concatenating :class:`str` objects, you can build a list and use
- :meth:`str.join` at the end;
+ :meth:`str.join` at the end or else write to a :class:`io.StringIO`
+ instance and retrieve its value when complete
* if concatenating :class:`bytes` objects, you can similarly use
- :meth:`bytes.join`, or you can do in-place concatenation with a
- :class:`bytearray` object. :class:`bytearray` objects are mutable and
- have an efficient overallocation mechanism.
+ :meth:`bytes.join` or :class:`io.BytesIO`, or you can do in-place
+ concatenation with a :class:`bytearray` object. :class:`bytearray`
+ objects are mutable and have an efficient overallocation mechanism
+
+ * if concatenating :class:`tuple` objects, extend a :class:`list` instead
+
+ * for other types, investigate the relevant class documentation
+
+
+(7)
+ Some sequence types (such as :class:`range`) only support item sequences
+ that follow specific patterns, and hence don't support sequence
+ concatenation or repetition.
+
+(8)
+ ``index`` raises :exc:`ValueError` when *x* is not found in *s*.
+ When supported, the additional arguments to the index method allow
+ efficient searching of subsections of the sequence. Passing the extra
+ arguments is roughly equivalent to using ``s[i:j].index(x)``, only
+ without copying any data and with the returned index being relative to
+ the start of the sequence rather than the start of the slice.
+
+
+.. _typesseq-immutable:
+
+Immutable Sequence Types
+------------------------
+
+.. index::
+ triple: immutable; sequence; types
+ object: tuple
+ builtin: hash
+
+The only operation that immutable sequence types generally implement that is
+not also implemented by mutable sequence types is support for the :func:`hash`
+built-in.
+
+This support allows immutable sequences, such as :class:`tuple` instances, to
+be used as :class:`dict` keys and stored in :class:`set` and :class:`frozenset`
+instances.
+
+Attempting to hash an immutable sequence that contains unhashable values will
+result in :exc:`TypeError`.
+
+
+.. _typesseq-mutable:
+
+Mutable Sequence Types
+----------------------
+
+.. index::
+ triple: mutable; sequence; types
+ object: list
+ object: bytearray
+
+The operations in the following table are defined on mutable sequence types.
+The :class:`collections.abc.MutableSequence` ABC is provided to make it
+easier to correctly implement these operations on custom sequence types.
+
+In the table *s* is an instance of a mutable sequence type, *t* is any
+iterable object and *x* is an arbitrary object that meets any type
+and value restrictions imposed by *s* (for example, :class:`bytearray` only
+accepts integers that meet the value restriction ``0 <= x <= 255``).
+
+
+.. index::
+ triple: operations on; sequence; types
+ triple: operations on; list; type
+ pair: subscript; assignment
+ pair: slice; assignment
+ statement: del
+ single: append() (sequence method)
+ single: clear() (sequence method)
+ single: copy() (sequence method)
+ single: extend() (sequence method)
+ single: insert() (sequence method)
+ single: pop() (sequence method)
+ single: remove() (sequence method)
+ single: reverse() (sequence method)
+
++------------------------------+--------------------------------+---------------------+
+| Operation | Result | Notes |
++==============================+================================+=====================+
+| ``s[i] = x`` | item *i* of *s* is replaced by | |
+| | *x* | |
++------------------------------+--------------------------------+---------------------+
+| ``s[i:j] = t`` | slice of *s* from *i* to *j* | |
+| | is replaced by the contents of | |
+| | the iterable *t* | |
++------------------------------+--------------------------------+---------------------+
+| ``del s[i:j]`` | same as ``s[i:j] = []`` | |
++------------------------------+--------------------------------+---------------------+
+| ``s[i:j:k] = t`` | the elements of ``s[i:j:k]`` | \(1) |
+| | are replaced by those of *t* | |
++------------------------------+--------------------------------+---------------------+
+| ``del s[i:j:k]`` | removes the elements of | |
+| | ``s[i:j:k]`` from the list | |
++------------------------------+--------------------------------+---------------------+
+| ``s.append(x)`` | appends *x* to the end of the | |
+| | sequence (same as | |
+| | ``s[len(s):len(s)] = [x]``) | |
++------------------------------+--------------------------------+---------------------+
+| ``s.clear()`` | removes all items from ``s`` | \(5) |
+| | (same as ``del s[:]``) | |
++------------------------------+--------------------------------+---------------------+
+| ``s.copy()`` | creates a shallow copy of ``s``| \(5) |
+| | (same as ``s[:]``) | |
++------------------------------+--------------------------------+---------------------+
+| ``s.extend(t)`` | extends *s* with the | |
+| | contents of *t* (same as | |
+| | ``s[len(s):len(s)] = t``) | |
++------------------------------+--------------------------------+---------------------+
+| ``s.insert(i, x)`` | inserts *x* into *s* at the | |
+| | index given by *i* | |
+| | (same as ``s[i:i] = [x]``) | |
++------------------------------+--------------------------------+---------------------+
+| ``s.pop([i])`` | retrieves the item at *i* and | \(2) |
+| | also removes it from *s* | |
++------------------------------+--------------------------------+---------------------+
+| ``s.remove(x)`` | remove the first item from *s* | \(3) |
+| | where ``s[i] == x`` | |
++------------------------------+--------------------------------+---------------------+
+| ``s.reverse()`` | reverses the items of *s* in | \(4) |
+| | place | |
++------------------------------+--------------------------------+---------------------+
+
+
+Notes:
+
+(1)
+ *t* must have the same length as the slice it is replacing.
+
+(2)
+ The optional argument *i* defaults to ``-1``, so that by default the last
+ item is removed and returned.
+
+(3)
+ ``remove`` raises :exc:`ValueError` when *x* is not found in *s*.
+
+(4)
+ The :meth:`reverse` method modifies the sequence in place for economy of
+ space when reversing a large sequence. To remind users that it operates by
+ side effect, it does not return the reversed sequence.
+
+(5)
+ :meth:`clear` and :meth:`!copy` are included for consistency with the
+ interfaces of mutable containers that don't support slicing operations
+ (such as :class:`dict` and :class:`set`)
+
+ .. versionadded:: 3.3
+ :meth:`clear` and :meth:`!copy` methods.
+
+
+.. _typesseq-list:
+
+Lists
+-----
+
+.. index:: object: list
+
+Lists are mutable sequences, typically used to store collections of
+homogeneous items (where the precise degree of similarity will vary by
+application).
+
+.. class:: list([iterable])
+
+ Lists may be constructed in several ways:
+
+ * Using a pair of square brackets to denote the empty list: ``[]``
+ * Using square brackets, separating items with commas: ``[a]``, ``[a, b, c]``
+ * Using a list comprehension: ``[x for x in iterable]``
+ * Using the type constructor: ``list()`` or ``list(iterable)``
+
+ The constructor builds a list whose items are the same and in the same
+ order as *iterable*'s items. *iterable* may be either a sequence, a
+ container that supports iteration, or an iterator object. If *iterable*
+ is already a list, a copy is made and returned, similar to ``iterable[:]``.
+ For example, ``list('abc')`` returns ``['a', 'b', 'c']`` and
+ ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``.
+ If no argument is given, the constructor creates a new empty list, ``[]``.
+
+
+ Many other operations also produce lists, including the :func:`sorted`
+ built-in.
+
+ Lists implement all of the :ref:`common <typesseq-common>` and
+ :ref:`mutable <typesseq-mutable>` sequence operations. Lists also provide the
+ following additional method:
+
+ .. method:: list.sort(*, key=None, reverse=None)
+
+ This method sorts the list in place, using only ``<`` comparisons
+ between items. Exceptions are not suppressed - if any comparison operations
+ fail, the entire sort operation will fail (and the list will likely be left
+ in a partially modified state).
+
+ *key* specifies a function of one argument that is used to extract a
+ comparison key from each list element (for example, ``key=str.lower``).
+ The key corresponding to each item in the list is calculated once and
+ then used for the entire sorting process. The default value of ``None``
+ means that list items are sorted directly without calculating a separate
+ key value.
+
+ The :func:`functools.cmp_to_key` utility is available to convert a 2.x
+ style *cmp* function to a *key* function.
+
+ *reverse* is a boolean value. If set to ``True``, then the list elements
+ are sorted as if each comparison were reversed.
+
+ This method modifies the sequence in place for economy of space when
+ sorting a large sequence. To remind users that it operates by side
+ effect, it does not return the sorted sequence (use :func:`sorted` to
+ explicitly request a new sorted list instance).
+
+ The :meth:`sort` method is guaranteed to be stable. A sort is stable if it
+ guarantees not to change the relative order of elements that compare equal
+ --- this is helpful for sorting in multiple passes (for example, sort by
+ department, then by salary grade).
+
+ .. impl-detail::
+
+ While a list is being sorted, the effect of attempting to mutate, or even
+ inspect, the list is undefined. The C implementation of Python makes the
+ list appear empty for the duration, and raises :exc:`ValueError` if it can
+ detect that the list has been mutated during a sort.
+
- .. class:: range([start, ]stop[, step])
+.. _typesseq-tuple:
+
+Tuples
+------
+
+.. index:: object: tuple
+
+Tuples are immutable sequences, typically used to store collections of
+heterogeneous data (such as the 2-tuples produced by the :func:`enumerate`
+built-in). Tuples are also used for cases where an immutable sequence of
+homogeneous data is needed (such as allowing storage in a :class:`set` or
+:class:`dict` instance).
+
+.. class:: tuple([iterable])
+
+ Tuples may be constructed in a number of ways:
+
+ * Using a pair of parentheses to denote the empty tuple: ``()``
+ * Using a trailing comma for a singleton tuple: ``a,`` or ``(a,)``
+ * Separating items with commas: ``a, b, c`` or ``(a, b, c)``
+ * Using the :func:`tuple` built-in: ``tuple()`` or ``tuple(iterable)``
+
+ The constructor builds a tuple whose items are the same and in the same
+ order as *iterable*'s items. *iterable* may be either a sequence, a
+ container that supports iteration, or an iterator object. If *iterable*
+ is already a tuple, it is returned unchanged. For example,
+ ``tuple('abc')`` returns ``('a', 'b', 'c')`` and
+ ``tuple( [1, 2, 3] )`` returns ``(1, 2, 3)``.
+ If no argument is given, the constructor creates a new empty tuple, ``()``.
+
+ Note that it is actually the comma which makes a tuple, not the parentheses.
+ The parentheses are optional, except in the empty tuple case, or
+ when they are needed to avoid syntactic ambiguity. For example,
+ ``f(a, b, c)`` is a function call with three arguments, while
+ ``f((a, b, c))`` is a function call with a 3-tuple as the sole argument.
+
+ Tuples implement all of the :ref:`common <typesseq-common>` sequence
+ operations.
+
+For heterogeneous collections of data where access by name is clearer than
+access by index, :func:`collections.namedtuple` may be a more appropriate
+choice than a simple tuple object.
+
+
+.. _typesseq-range:
+
+Ranges
+------
+
+.. index:: object: range
+
+The :class:`range` type represents an immutable sequence of numbers and is
+commonly used for looping a specific number of times in :keyword:`for`
+loops.
+
++.. class:: range(stop)
++ range(start, stop[, step])
+
+ The arguments to the range constructor must be integers (either built-in
+ :class:`int` or any object that implements the ``__index__`` special
+ method). If the *step* argument is omitted, it defaults to ``1``.
+ If the *start* argument is omitted, it defaults to ``0``.
+ If *step* is zero, :exc:`ValueError` is raised.
+
+ For a positive *step*, the contents of a range ``r`` are determined by the
+ formula ``r[i] = start + step*i`` where ``i >= 0`` and
+ ``r[i] < stop``.
+
+ For a negative *step*, the contents of the range are still determined by
+ the formula ``r[i] = start + step*i``, but the constraints are ``i >= 0``
+ and ``r[i] > stop``.
+
+ A range object will be empty if ``r[0]`` does not meant the value
+ constraint. Ranges do support negative indices, but these are interpreted
+ as indexing from the end of the sequence determined by the positive
+ indices.
+
+ Ranges containing absolute values larger than :data:`sys.maxsize` are
+ permitted but some features (such as :func:`len`) may raise
+ :exc:`OverflowError`.
+
+ Range examples::
+
+ >>> list(range(10))
+ [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+ >>> list(range(1, 11))
+ [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+ >>> list(range(0, 30, 5))
+ [0, 5, 10, 15, 20, 25]
+ >>> list(range(0, 10, 3))
+ [0, 3, 6, 9]
+ >>> list(range(0, -10, -1))
+ [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
+ >>> list(range(0))
+ []
+ >>> list(range(1, 0))
+ []
+
+ Ranges implement all of the :ref:`common <typesseq-common>` sequence operations
+ except concatenation and repetition (due to the fact that range objects can
+ only represent sequences that follow a strict pattern and repetition and
+ concatenation will usually violate that pattern).
+
+ .. data: start
+
+ The value of the *start* parameter (or ``0`` if the parameter was
+ not supplied)
+
+ .. data: stop
+
+ The value of the *stop* parameter
+
+ .. data: step
+
+ The value of the *step* parameter (or ``1`` if the parameter was
+ not supplied)
+
+The advantage of the :class:`range` type over a regular :class:`list` or
+:class:`tuple` is that a :class:`range` object will always take the same
+(small) amount of memory, no matter the size of the range it represents (as it
+only stores the ``start``, ``stop`` and ``step`` values, calculating individual
+items and subranges as needed).
+
+Range objects implement the :class:`collections.Sequence` ABC, and provide
+features such as containment tests, element index lookup, slicing and
+support for negative indices (see :ref:`typesseq`):
+
+ >>> r = range(0, 20, 2)
+ >>> r
+ range(0, 20, 2)
+ >>> 11 in r
+ False
+ >>> 10 in r
+ True
+ >>> r.index(10)
+ 5
+ >>> r[5]
+ 10
+ >>> r[:5]
+ range(0, 10, 2)
+ >>> r[-1]
+ 18
+
+Testing range objects for equality with ``==`` and ``!=`` compares
+them as sequences. That is, two range objects are considered equal if
+they represent the same sequence of values. (Note that two range
+objects that compare equal might have different :attr:`start`,
+:attr:`stop` and :attr:`step` attributes, for example ``range(0) ==
+range(2, 1, 3)`` or ``range(0, 3, 2) == range(0, 4, 2)``.)
+
+.. versionchanged:: 3.2
+ Implement the Sequence ABC.
+ Support slicing and negative indices.
+ Test :class:`int` objects for membership in constant time instead of
+ iterating through all items.
+
+.. versionchanged:: 3.3
+ Define '==' and '!=' to compare range objects based on the
+ sequence of values they define (instead of comparing based on
+ object identity).
+
+.. versionadded:: 3.3
+ The :attr:`start`, :attr:`stop` and :attr:`step` attributes.
+
+
+.. _textseq:
+
+Text Sequence Type --- :class:`str`
+===================================
+
+.. index::
+ object: string
+ object: bytes
+ object: bytearray
+ object: io.StringIO
+
+
+Textual data in Python is handled with :class:`str` objects, which are
+immutable sequences of Unicode code points. String literals are
+written in a variety of ways:
+
+* Single quotes: ``'allows embedded "double" quotes'``
+* Double quotes: ``"allows embedded 'single' quotes"``.
+* Triple quoted: ``'''Three single quotes'''``, ``"""Three double quotes"""``
+
+Triple quoted strings may span multiple lines - all associated whitespace will
+be included in the string literal.
+
+String literals that are part of a single expression and have only whitespace
+between them will be implicitly converted to a single string literal. That
+is, ``("spam " "eggs") == "spam eggs"``.
+
+See :ref:`strings` for more about the various forms of string literal,
+including supported escape sequences, and the ``r`` ("raw") prefix that
+disables most escape sequence processing.
+
+Strings may also be created from other objects with the :ref:`str <func-str>`
+built-in.
+
+Since there is no separate "character" type, indexing a string produces
+strings of length 1. That is, for a non-empty string *s*, ``s[0] == s[0:1]``.
+
+There is also no mutable string type, but :meth:`str.join` or
+:class:`io.StringIO` can be used to efficiently construct strings from
+multiple fragments.
+
+.. versionchanged:: 3.3
+ For backwards compatibility with the Python 2 series, the ``u`` prefix is
+ once again permitted on string literals. It has no effect on the meaning
+ of string literals and cannot be combined with the ``r`` prefix.
.. _string-methods:
projects / python / commitdiff