From: Ezio Melotti Date: Fri, 14 Sep 2012 03:35:09 +0000 (+0300) Subject: #15831: merge with 3.2 X-Git-Tag: v3.3.1rc1~818^2^2~76 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=8429b6784bd7447055c7880e1b84954cd27bd0a3;p=thirdparty%2FPython%2Fcpython.git #15831: merge with 3.2 --- 8429b6784bd7447055c7880e1b84954cd27bd0a3 diff --cc Doc/library/curses.rst index 2d0043cbd183,11ab5d01057a..9e5cb554f0ce --- a/Doc/library/curses.rst +++ b/Doc/library/curses.rst @@@ -653,10 -643,11 +654,11 @@@ Window Object -------------- Window objects, as returned by :func:`initscr` and :func:`newwin` above, have -the following methods: +the following methods and attributes: - .. method:: window.addch([y, x,] ch[, attr]) + .. method:: window.addch(ch[, attr]) + window.addch(y, x, ch[, attr]) .. note:: diff --cc Doc/library/functions.rst index 61e4932f0691,be5d4c7e278c..6156c5d1e87f --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@@ -970,9 -967,9 +980,9 @@@ are always available. They are listed 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. @@@ -1060,12 -1054,63 +1070,13 @@@ ``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) diff --cc Doc/library/inspect.rst index 9b7ae9cd8d34,d127ce8cfcd7..d1d2dea29bb5 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@@ -395,264 -374,6 +395,264 @@@ Retrieving source cod onwards is removed. Also, all tabs are expanded to spaces. +.. _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 + + + 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:: Signature.replace([parameters], *, [return_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]) ++ .. 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 diff --cc Doc/library/multiprocessing.rst index f2b2a8ac7752,4271fc259768..616b7cd5565c --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@@ -295,7 -298,7 +295,8 @@@ The :mod:`multiprocessing` package most :class:`Process` and exceptions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. class:: Process([group[, target[, name[, args[, kwargs]]]]], *, daemon=None) -.. class:: Process(group=None, target=None, name=None, args=(), kwargs={}) ++.. class:: Process(group=None, target=None, name=None, args=(), kwargs={}, \ ++ *, daemon=None) Process objects represent activity that is run in a separate process. The :class:`Process` class has equivalents of all the methods of diff --cc Doc/library/stdtypes.rst index 3c038beec4f8,968839369558..ed5b3aeb62e9 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@@ -943,452 -965,19 +943,453 @@@ Notes 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 ` and + :ref:`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. + +.. _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 ` 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([start, ]stop[, step]) ++.. 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 ` 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 ` +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: