FM / library

/usr/share/doc/python2-docs/html/_sources/library/

/usr/share/doc/python2-docs/html/_sources/library

Name	Size	Mode	Actions
2to3.rst.txt	14647	0644	edit dl rm
abc.rst.txt	7219	0644	edit dl rm
aepack.rst.txt	4257	0644	edit dl rm
aetools.rst.txt	3532	0644	edit dl rm
aetypes.rst.txt	4257	0644	edit dl rm
aifc.rst.txt	7086	0644	edit dl rm
al.rst.txt	5309	0644	edit dl rm
allos.rst.txt	695	0644	edit dl rm
anydbm.rst.txt	4111	0644	edit dl rm
archiving.rst.txt	424	0644	edit dl rm
argparse.rst.txt	74685	0644	edit dl rm
array.rst.txt	10524	0644	edit dl rm
ast.rst.txt	10111	0644	edit dl rm
asynchat.rst.txt	9206	0644	edit dl rm
asyncore.rst.txt	12937	0644	edit dl rm
atexit.rst.txt	3910	0644	edit dl rm
audioop.rst.txt	10395	0644	edit dl rm
autogil.rst.txt	1015	0644	edit dl rm
base64.rst.txt	6252	0644	edit dl rm
basehttpserver.rst.txt	10404	0644	edit dl rm
bastion.rst.txt	2611	0644	edit dl rm
bdb.rst.txt	12456	0644	edit dl rm
binascii.rst.txt	6508	0644	edit dl rm
binhex.rst.txt	1910	0644	edit dl rm
bisect.rst.txt	5415	0644	edit dl rm
bsddb.rst.txt	7575	0644	edit dl rm
bz2.rst.txt	8064	0644	edit dl rm
calendar.rst.txt	11282	0644	edit dl rm
carbon.rst.txt	15956	0644	edit dl rm
cd.rst.txt	11974	0644	edit dl rm
cgi.rst.txt	22853	0644	edit dl rm
cgihttpserver.rst.txt	2788	0644	edit dl rm
cgitb.rst.txt	2874	0644	edit dl rm
chunk.rst.txt	4955	0644	edit dl rm
cmath.rst.txt	7647	0644	edit dl rm
cmd.rst.txt	8565	0644	edit dl rm
code.rst.txt	7115	0644	edit dl rm
codecs.rst.txt	66966	0644	edit dl rm
codeop.rst.txt	3774	0644	edit dl rm
collections.rst.txt	41448	0644	edit dl rm
colorpicker.rst.txt	913	0644	edit dl rm
colorsys.rst.txt	1819	0644	edit dl rm
commands.rst.txt	2595	0644	edit dl rm
compileall.rst.txt	4678	0644	edit dl rm
compiler.rst.txt	37464	0644	edit dl rm
configparser.rst.txt	19607	0644	edit dl rm
constants.rst.txt	2328	0644	edit dl rm
contextlib.rst.txt	6012	0644	edit dl rm
cookie.rst.txt	9543	0644	edit dl rm
cookielib.rst.txt	27875	0644	edit dl rm
copy.rst.txt	3351	0644	edit dl rm
copy_reg.rst.txt	2329	0644	edit dl rm
crypt.rst.txt	2292	0644	edit dl rm
crypto.rst.txt	355	0644	edit dl rm
csv.rst.txt	22757	0644	edit dl rm
ctypes.rst.txt	90513	0644	edit dl rm
curses.ascii.rst.txt	9046	0644	edit dl rm
curses.panel.rst.txt	2740	0644	edit dl rm
curses.rst.txt	74877	0644	edit dl rm
custominterp.rst.txt	570	0644	edit dl rm
datatypes.rst.txt	864	0644	edit dl rm
datetime.rst.txt	74679	0644	edit dl rm
dbhash.rst.txt	3865	0644	edit dl rm
dbm.rst.txt	3117	0644	edit dl rm
debug.rst.txt	446	0644	edit dl rm
decimal.rst.txt	70926	0644	edit dl rm
development.rst.txt	640	0644	edit dl rm
difflib.rst.txt	30716	0644	edit dl rm
dircache.rst.txt	1813	0644	edit dl rm
dis.rst.txt	23248	0644	edit dl rm
distribution.rst.txt	426	0644	edit dl rm
distutils.rst.txt	1958	0644	edit dl rm
dl.rst.txt	3392	0644	edit dl rm
doctest.rst.txt	73985	0644	edit dl rm
docxmlrpcserver.rst.txt	3802	0644	edit dl rm
dumbdbm.rst.txt	2841	0644	edit dl rm
dummy_thread.rst.txt	1058	0644	edit dl rm
dummy_threading.rst.txt	799	0644	edit dl rm
easydialogs.rst.txt	10346	0644	edit dl rm
email-examples.rst.txt	1271	0644	edit dl rm
email.charset.rst.txt	9654	0644	edit dl rm
email.encoders.rst.txt	2376	0644	edit dl rm
email.errors.rst.txt	4006	0644	edit dl rm
email.generator.rst.txt	6132	0644	edit dl rm
email.header.rst.txt	7531	0644	edit dl rm
email.iterators.rst.txt	2421	0644	edit dl rm
email.message.rst.txt	25217	0644	edit dl rm
email.mime.rst.txt	9917	0644	edit dl rm
email.parser.rst.txt	10327	0644	edit dl rm
email.rst.txt	16111	0644	edit dl rm
email.utils.rst.txt	6475	0644	edit dl rm
ensurepip.rst.txt	5022	0644	edit dl rm
errno.rst.txt	6708	0644	edit dl rm
exceptions.rst.txt	18343	0644	edit dl rm
fcntl.rst.txt	7361	0644	edit dl rm
filecmp.rst.txt	5348	0644	edit dl rm
fileformats.rst.txt	302	0644	edit dl rm
fileinput.rst.txt	7417	0644	edit dl rm
filesys.rst.txt	806	0644	edit dl rm
fl.rst.txt	17646	0644	edit dl rm
fm.rst.txt	2699	0644	edit dl rm
fnmatch.rst.txt	3104	0644	edit dl rm
formatter.rst.txt	13245	0644	edit dl rm
fpectl.rst.txt	4171	0644	edit dl rm
fpformat.rst.txt	1747	0644	edit dl rm
fractions.rst.txt	5297	0644	edit dl rm
framework.rst.txt	11444	0644	edit dl rm
frameworks.rst.txt	378	0644	edit dl rm
ftplib.rst.txt	15720	0644	edit dl rm
functions.rst.txt	75554	0644	edit dl rm
functools.rst.txt	7448	0644	edit dl rm
future_builtins.rst.txt	2010	0644	edit dl rm
gc.rst.txt	9014	0644	edit dl rm
gdbm.rst.txt	4882	0644	edit dl rm
gensuitemodule.rst.txt	3113	0644	edit dl rm
getopt.rst.txt	6670	0644	edit dl rm
getpass.rst.txt	1876	0644	edit dl rm
gettext.rst.txt	29040	0644	edit dl rm
gl.rst.txt	6009	0644	edit dl rm
glob.rst.txt	2414	0644	edit dl rm
grp.rst.txt	2256	0644	edit dl rm
gzip.rst.txt	4828	0644	edit dl rm
hashlib.rst.txt	7379	0644	edit dl rm
heapq.rst.txt	13185	0644	edit dl rm
hmac.rst.txt	3073	0644	edit dl rm
hotshot.rst.txt	4289	0644	edit dl rm
htmllib.rst.txt	7379	0644	edit dl rm
htmlparser.rst.txt	11640	0644	edit dl rm
httplib.rst.txt	37454	0644	edit dl rm
i18n.rst.txt	409	0644	edit dl rm
ic.rst.txt	5005	0644	edit dl rm
idle.rst.txt	22182	0644	edit dl rm
imageop.rst.txt	4001	0644	edit dl rm
imaplib.rst.txt	17221	0644	edit dl rm
imgfile.rst.txt	2765	0644	edit dl rm
imghdr.rst.txt	2635	0644	edit dl rm
imp.rst.txt	12593	0644	edit dl rm
importlib.rst.txt	1126	0644	edit dl rm
imputil.rst.txt	7023	0644	edit dl rm
index.rst.txt	2287	0644	edit dl rm
inspect.rst.txt	28151	0644	edit dl rm
internet.rst.txt	950	0644	edit dl rm
intro.rst.txt	2803	0644	edit dl rm
io.rst.txt	39015	0644	edit dl rm
ipc.rst.txt	630	0644	edit dl rm
itertools.rst.txt	36324	0644	edit dl rm
jpeg.rst.txt	3858	0644	edit dl rm
json.rst.txt	25545	0644	edit dl rm
keyword.rst.txt	617	0644	edit dl rm
language.rst.txt	523	0644	edit dl rm
linecache.rst.txt	1887	0644	edit dl rm
locale.rst.txt	24975	0644	edit dl rm
logging.config.rst.txt	31560	0644	edit dl rm
logging.handlers.rst.txt	28153	0644	edit dl rm
logging.rst.txt	46882	0644	edit dl rm
mac.rst.txt	791	0644	edit dl rm
macos.rst.txt	3824	0644	edit dl rm
macosa.rst.txt	3964	0644	edit dl rm
macostools.rst.txt	4017	0644	edit dl rm
macpath.rst.txt	650	0644	edit dl rm
mailbox.rst.txt	68129	0644	edit dl rm
mailcap.rst.txt	3675	0644	edit dl rm
markup.rst.txt	1249	0644	edit dl rm
marshal.rst.txt	5689	0644	edit dl rm
math.rst.txt	10920	0644	edit dl rm
md5.rst.txt	2815	0644	edit dl rm
mhlib.rst.txt	3966	0644	edit dl rm
mimetools.rst.txt	4504	0644	edit dl rm
mimetypes.rst.txt	9839	0644	edit dl rm
mimewriter.rst.txt	3360	0644	edit dl rm
mimify.rst.txt	3519	0644	edit dl rm
miniaeframe.rst.txt	2564	0644	edit dl rm
misc.rst.txt	248	0644	edit dl rm
mm.rst.txt	447	0644	edit dl rm
mmap.rst.txt	10481	0644	edit dl rm
modulefinder.rst.txt	3380	0644	edit dl rm
modules.rst.txt	382	0644	edit dl rm
msilib.rst.txt	19062	0644	edit dl rm
msvcrt.rst.txt	4346	0644	edit dl rm
multifile.rst.txt	6613	0644	edit dl rm
multiprocessing.rst.txt	92621	0644	edit dl rm
mutex.rst.txt	1939	0644	edit dl rm
netdata.rst.txt	432	0644	edit dl rm
netrc.rst.txt	3119	0644	edit dl rm
new.rst.txt	2653	0644	edit dl rm
nis.rst.txt	2108	0644	edit dl rm
nntplib.rst.txt	14531	0644	edit dl rm
numbers.rst.txt	8007	0644	edit dl rm
numeric.rst.txt	751	0644	edit dl rm
operator.rst.txt	22092	0644	edit dl rm
optparse.rst.txt	77101	0644	edit dl rm
os.path.rst.txt	13094	0644	edit dl rm
os.rst.txt	82580	0644	edit dl rm
ossaudiodev.rst.txt	17309	0644	edit dl rm
othergui.rst.txt	2721	0644	edit dl rm
parser.rst.txt	15385	0644	edit dl rm
pdb.rst.txt	16043	0644	edit dl rm
persistence.rst.txt	826	0644	edit dl rm
pickle.rst.txt	37262	0644	edit dl rm
pickletools.rst.txt	1997	0644	edit dl rm
pipes.rst.txt	3786	0644	edit dl rm
pkgutil.rst.txt	7714	0644	edit dl rm
platform.rst.txt	9554	0644	edit dl rm
plistlib.rst.txt	4134	0644	edit dl rm
popen2.rst.txt	7022	0644	edit dl rm
poplib.rst.txt	6220	0644	edit dl rm
posix.rst.txt	3630	0644	edit dl rm
posixfile.rst.txt	7200	0644	edit dl rm
pprint.rst.txt	9071	0644	edit dl rm
profile.rst.txt	28666	0644	edit dl rm
pty.rst.txt	1762	0644	edit dl rm
pwd.rst.txt	2725	0644	edit dl rm
pyclbr.rst.txt	3296	0644	edit dl rm
pydoc.rst.txt	4083	0644	edit dl rm
pyexpat.rst.txt	28891	0644	edit dl rm
python.rst.txt	514	0644	edit dl rm
py_compile.rst.txt	2479	0644	edit dl rm
queue.rst.txt	7034	0644	edit dl rm
quopri.rst.txt	2670	0644	edit dl rm
random.rst.txt	13319	0644	edit dl rm
re.rst.txt	55102	0644	edit dl rm
readline.rst.txt	10513	0644	edit dl rm
repr.rst.txt	4718	0644	edit dl rm
resource.rst.txt	9595	0644	edit dl rm
restricted.rst.txt	3327	0644	edit dl rm
rexec.rst.txt	11742	0644	edit dl rm
rfc822.rst.txt	14037	0644	edit dl rm
rlcompleter.rst.txt	2494	0644	edit dl rm
robotparser.rst.txt	2190	0644	edit dl rm
runpy.rst.txt	6938	0644	edit dl rm
sched.rst.txt	4644	0644	edit dl rm
scrolledtext.rst.txt	1379	0644	edit dl rm
select.rst.txt	20705	0644	edit dl rm
sets.rst.txt	14973	0644	edit dl rm
sgi.rst.txt	322	0644	edit dl rm
sgmllib.rst.txt	10664	0644	edit dl rm
sha.rst.txt	2807	0644	edit dl rm
shelve.rst.txt	8319	0644	edit dl rm
shlex.rst.txt	11313	0644	edit dl rm
shutil.rst.txt	13491	0644	edit dl rm
signal.rst.txt	10719	0644	edit dl rm
simplehttpserver.rst.txt	4559	0644	edit dl rm
simplexmlrpcserver.rst.txt	10881	0644	edit dl rm
site.rst.txt	7880	0644	edit dl rm
smtpd.rst.txt	2464	0644	edit dl rm
smtplib.rst.txt	14906	0644	edit dl rm
sndhdr.rst.txt	1759	0644	edit dl rm
socket.rst.txt	40765	0644	edit dl rm
socketserver.rst.txt	22512	0644	edit dl rm
someos.rst.txt	599	0644	edit dl rm
spwd.rst.txt	2825	0644	edit dl rm
sqlite3.rst.txt	35448	0644	edit dl rm
ssl.rst.txt	76554	0644	edit dl rm
stat.rst.txt	7778	0644	edit dl rm
statvfs.rst.txt	1300	0644	edit dl rm
stdtypes.rst.txt	122668	0644	edit dl rm
string.rst.txt	44085	0644	edit dl rm
stringio.rst.txt	4166	0644	edit dl rm
stringprep.rst.txt	4238	0644	edit dl rm
strings.rst.txt	746	0644	edit dl rm
struct.rst.txt	17100	0644	edit dl rm
subprocess.rst.txt	33648	0644	edit dl rm
sun.rst.txt	249	0644	edit dl rm
sunau.rst.txt	7124	0644	edit dl rm
sunaudio.rst.txt	5849	0644	edit dl rm
symbol.rst.txt	975	0644	edit dl rm
symtable.rst.txt	5064	0644	edit dl rm
sys.rst.txt	47520	0644	edit dl rm
sysconfig.rst.txt	7639	0644	edit dl rm
syslog.rst.txt	3931	0644	edit dl rm
tabnanny.rst.txt	1999	0644	edit dl rm
tarfile.rst.txt	28214	0644	edit dl rm
telnetlib.rst.txt	7482	0644	edit dl rm
tempfile.rst.txt	10504	0644	edit dl rm
termios.rst.txt	3733	0644	edit dl rm
test.rst.txt	17659	0644	edit dl rm
textwrap.rst.txt	8552	0644	edit dl rm
thread.rst.txt	6588	0644	edit dl rm
threading.rst.txt	32468	0644	edit dl rm
time.rst.txt	26020	0644	edit dl rm
timeit.rst.txt	11598	0644	edit dl rm
tix.rst.txt	22693	0644	edit dl rm
tk.rst.txt	1612	0644	edit dl rm
tkinter.rst.txt	33456	0644	edit dl rm
token.rst.txt	2451	0644	edit dl rm
tokenize.rst.txt	5570	0644	edit dl rm
trace.rst.txt	6724	0644	edit dl rm
traceback.rst.txt	10711	0644	edit dl rm
ttk.rst.txt	57411	0644	edit dl rm
tty.rst.txt	1011	0644	edit dl rm
turtle.rst.txt	64097	0644	edit dl rm
types.rst.txt	6200	0644	edit dl rm
undoc.rst.txt	6550	0644	edit dl rm
unicodedata.rst.txt	5736	0644	edit dl rm
unittest.rst.txt	82952	0644	edit dl rm
unix.rst.txt	490	0644	edit dl rm
urllib.rst.txt	24960	0644	edit dl rm
urllib2.rst.txt	35211	0644	edit dl rm
urlparse.rst.txt	16071	0644	edit dl rm
user.rst.txt	2748	0644	edit dl rm
userdict.rst.txt	9290	0644	edit dl rm
uu.rst.txt	2369	0644	edit dl rm
uuid.rst.txt	8378	0644	edit dl rm
warnings.rst.txt	19815	0644	edit dl rm
wave.rst.txt	5047	0644	edit dl rm
weakref.rst.txt	12926	0644	edit dl rm
webbrowser.rst.txt	9863	0644	edit dl rm
whichdb.rst.txt	931	0644	edit dl rm
windows.rst.txt	273	0644	edit dl rm
winsound.rst.txt	5066	0644	edit dl rm
wsgiref.rst.txt	30567	0644	edit dl rm
xdrlib.rst.txt	8077	0644	edit dl rm
xml.dom.minidom.rst.txt	11208	0644	edit dl rm
xml.dom.pulldom.rst.txt	1571	0644	edit dl rm
xml.dom.rst.txt	40182	0644	edit dl rm
xml.etree.elementtree.rst.txt	35707	0644	edit dl rm
xml.rst.txt	6090	0644	edit dl rm
xml.sax.handler.rst.txt	15371	0644	edit dl rm
xml.sax.reader.rst.txt	12257	0644	edit dl rm
xml.sax.rst.txt	6460	0644	edit dl rm
xml.sax.utils.rst.txt	3560	0644	edit dl rm
xmlrpclib.rst.txt	22559	0644	edit dl rm
zipfile.rst.txt	18871	0644	edit dl rm
zipimport.rst.txt	5957	0644	edit dl rm
zlib.rst.txt	12766	0644	edit dl rm
_winreg.rst.txt	23305	0644	edit dl rm
__builtin__.rst.txt	1494	0644	edit dl rm
__future__.rst.txt	4952	0644	edit dl rm
__main__.rst.txt	535	0644	edit dl rm

Edit: /usr/share/doc/python2-docs/html/_sources/library/itertools.rst.txt (36324B)

:mod:`itertools` --- Functions creating iterators for efficient looping
=======================================================================

.. module:: itertools
   :synopsis: Functions creating iterators for efficient looping.
.. moduleauthor:: Raymond Hettinger <python@rcn.com>
.. sectionauthor:: Raymond Hettinger <python@rcn.com>

.. testsetup::

from itertools import *

.. versionadded:: 2.3

This module implements a number of :term:`iterator` building blocks inspired
by constructs from APL, Haskell, and SML.  Each has been recast in a form
suitable for Python.

The module standardizes a core set of fast, memory efficient tools that are
useful by themselves or in combination.  Together, they form an "iterator
algebra" making it possible to construct specialized tools succinctly and
efficiently in pure Python.

For instance, SML provides a tabulation tool: ``tabulate(f)`` which produces a
sequence ``f(0), f(1), ...``.  The same effect can be achieved in Python
by combining :func:`imap` and :func:`count` to form ``imap(f, count())``.

These tools and their built-in counterparts also work well with the high-speed
functions in the :mod:`operator` module.  For example, the multiplication
operator can be mapped across two vectors to form an efficient dot-product:
``sum(imap(operator.mul, vector1, vector2))``.

**Infinite Iterators:**

==================  =================       =================================================               =========================================
Iterator            Arguments               Results                                                         Example
==================  =================       =================================================               =========================================
:func:`count`       start, [step]           start, start+step, start+2*step, ...                            ``count(10) --> 10 11 12 13 14 ...``
:func:`cycle`       p                       p0, p1, ... plast, p0, p1, ...                                  ``cycle('ABCD') --> A B C D A B C D ...``
:func:`repeat`      elem [,n]               elem, elem, elem, ... endlessly or up to n times                ``repeat(10, 3) --> 10 10 10``
==================  =================       =================================================               =========================================

**Iterators terminating on the shortest input sequence:**

====================    ============================    =================================================   =============================================================
Iterator                Arguments                       Results                                             Example
====================    ============================    =================================================   =============================================================
:func:`chain`           p, q, ...                       p0, p1, ... plast, q0, q1, ...                      ``chain('ABC', 'DEF') --> A B C D E F``
:func:`compress`        data, selectors                 (d[0] if s[0]), (d[1] if s[1]), ...                 ``compress('ABCDEF', [1,0,1,0,1,1]) --> A C E F``
:func:`dropwhile`       pred, seq                       seq[n], seq[n+1], starting when pred fails          ``dropwhile(lambda x: x<5, [1,4,6,4,1]) --> 6 4 1``
:func:`groupby`         iterable[, keyfunc]             sub-iterators grouped by value of keyfunc(v)
:func:`ifilter`         pred, seq                       elements of seq where pred(elem) is true            ``ifilter(lambda x: x%2, range(10)) --> 1 3 5 7 9``
:func:`ifilterfalse`    pred, seq                       elements of seq where pred(elem) is false           ``ifilterfalse(lambda x: x%2, range(10)) --> 0 2 4 6 8``
:func:`islice`          seq, [start,] stop [, step]     elements from seq[start:stop:step]                  ``islice('ABCDEFG', 2, None) --> C D E F G``
:func:`imap`            func, p, q, ...                 func(p0, q0), func(p1, q1), ...                     ``imap(pow, (2,3,10), (5,2,3)) --> 32 9 1000``
:func:`starmap`         func, seq                       func(\*seq[0]), func(\*seq[1]), ...                 ``starmap(pow, [(2,5), (3,2), (10,3)]) --> 32 9 1000``
:func:`tee`             it, n                           it1, it2, ... itn  splits one iterator into n
:func:`takewhile`       pred, seq                       seq[0], seq[1], until pred fails                    ``takewhile(lambda x: x<5, [1,4,6,4,1]) --> 1 4``
:func:`izip`            p, q, ...                       (p[0], q[0]), (p[1], q[1]), ...                     ``izip('ABCD', 'xy') --> Ax By``
:func:`izip_longest`    p, q, ...                       (p[0], q[0]), (p[1], q[1]), ...                     ``izip_longest('ABCD', 'xy', fillvalue='-') --> Ax By C- D-``
====================    ============================    =================================================   =============================================================

**Combinatoric generators:**

==============================================   ====================       =============================================================
Iterator                                         Arguments                  Results
==============================================   ====================       =============================================================
:func:`product`                                  p, q, ... [repeat=1]       cartesian product, equivalent to a nested for-loop
:func:`permutations`                             p[, r]                     r-length tuples, all possible orderings, no repeated elements
:func:`combinations`                             p, r                       r-length tuples, in sorted order, no repeated elements
:func:`combinations_with_replacement`            p, r                       r-length tuples, in sorted order, with repeated elements
``product('ABCD', repeat=2)``                                               ``AA AB AC AD BA BB BC BD CA CB CC CD DA DB DC DD``
``permutations('ABCD', 2)``                                                 ``AB AC AD BA BC BD CA CB CD DA DB DC``
``combinations('ABCD', 2)``                                                 ``AB AC AD BC BD CD``
``combinations_with_replacement('ABCD', 2)``                                ``AA AB AC AD BB BC BD CC CD DD``
==============================================   ====================       =============================================================

.. _itertools-functions:

Itertool functions
------------------

The following module functions all construct and return iterators. Some provide
streams of infinite length, so they should only be accessed by functions or
loops that truncate the stream.

.. function:: chain(*iterables)

Make an iterator that returns elements from the first iterable until it is
   exhausted, then proceeds to the next iterable, until all of the iterables are
   exhausted.  Used for treating consecutive sequences as a single sequence.
   Roughly equivalent to::

def chain(*iterables):
          # chain('ABC', 'DEF') --> A B C D E F
          for it in iterables:
              for element in it:
                  yield element

.. classmethod:: chain.from_iterable(iterable)

Alternate constructor for :func:`chain`.  Gets chained inputs from a
   single iterable argument that is evaluated lazily.  Roughly equivalent to::

def from_iterable(iterables):
          # chain.from_iterable(['ABC', 'DEF']) --> A B C D E F
          for it in iterables:
              for element in it:
                  yield element

.. versionadded:: 2.6

.. function:: combinations(iterable, r)

Return *r* length subsequences of elements from the input *iterable*.

Combinations are emitted in lexicographic sort order.  So, if the
   input *iterable* is sorted, the combination tuples will be produced
   in sorted order.

Elements are treated as unique based on their position, not on their
   value.  So if the input elements are unique, there will be no repeat
   values in each combination.

Roughly equivalent to::

def combinations(iterable, r):
            # combinations('ABCD', 2) --> AB AC AD BC BD CD
            # combinations(range(4), 3) --> 012 013 023 123
            pool = tuple(iterable)
            n = len(pool)
            if r > n:
                return
            indices = range(r)
            yield tuple(pool[i] for i in indices)
            while True:
                for i in reversed(range(r)):
                    if indices[i] != i + n - r:
                        break
                else:
                    return
                indices[i] += 1
                for j in range(i+1, r):
                    indices[j] = indices[j-1] + 1
                yield tuple(pool[i] for i in indices)

The code for :func:`combinations` can be also expressed as a subsequence
   of :func:`permutations` after filtering entries where the elements are not
   in sorted order (according to their position in the input pool)::

def combinations(iterable, r):
            pool = tuple(iterable)
            n = len(pool)
            for indices in permutations(range(n), r):
                if sorted(indices) == list(indices):
                    yield tuple(pool[i] for i in indices)

The number of items returned is ``n! / r! / (n-r)!`` when ``0 <= r <= n``
   or zero when ``r > n``.

.. versionadded:: 2.6

.. function:: combinations_with_replacement(iterable, r)

Return *r* length subsequences of elements from the input *iterable*
   allowing individual elements to be repeated more than once.

Combinations are emitted in lexicographic sort order.  So, if the
   input *iterable* is sorted, the combination tuples will be produced
   in sorted order.

Elements are treated as unique based on their position, not on their
   value.  So if the input elements are unique, the generated combinations
   will also be unique.

Roughly equivalent to::

def combinations_with_replacement(iterable, r):
            # combinations_with_replacement('ABC', 2) --> AA AB AC BB BC CC
            pool = tuple(iterable)
            n = len(pool)
            if not n and r:
                return
            indices = [0] * r
            yield tuple(pool[i] for i in indices)
            while True:
                for i in reversed(range(r)):
                    if indices[i] != n - 1:
                        break
                else:
                    return
                indices[i:] = [indices[i] + 1] * (r - i)
                yield tuple(pool[i] for i in indices)

The code for :func:`combinations_with_replacement` can be also expressed as
   a subsequence of :func:`product` after filtering entries where the elements
   are not in sorted order (according to their position in the input pool)::

def combinations_with_replacement(iterable, r):
            pool = tuple(iterable)
            n = len(pool)
            for indices in product(range(n), repeat=r):
                if sorted(indices) == list(indices):
                    yield tuple(pool[i] for i in indices)

The number of items returned is ``(n+r-1)! / r! / (n-1)!`` when ``n > 0``.

.. versionadded:: 2.7

.. function:: compress(data, selectors)

Make an iterator that filters elements from *data* returning only those that
   have a corresponding element in *selectors* that evaluates to ``True``.
   Stops when either the *data* or *selectors* iterables has been exhausted.
   Roughly equivalent to::

def compress(data, selectors):
           # compress('ABCDEF', [1,0,1,0,1,1]) --> A C E F
           return (d for d, s in izip(data, selectors) if s)

.. versionadded:: 2.7

.. function:: count(start=0, step=1)

Make an iterator that returns evenly spaced values starting with *n*. Often
   used as an argument to :func:`imap` to generate consecutive data points.
   Also, used with :func:`izip` to add sequence numbers.  Equivalent to::

def count(start=0, step=1):
          # count(10) --> 10 11 12 13 14 ...
          # count(2.5, 0.5) -> 2.5 3.0 3.5 ...
          n = start
          while True:
              yield n
              n += step

When counting with floating point numbers, better accuracy can sometimes be
   achieved by substituting multiplicative code such as: ``(start + step * i
   for i in count())``.

.. versionchanged:: 2.7
      added *step* argument and allowed non-integer arguments.

.. function:: cycle(iterable)

Make an iterator returning elements from the iterable and saving a copy of each.
   When the iterable is exhausted, return elements from the saved copy.  Repeats
   indefinitely.  Roughly equivalent to::

def cycle(iterable):
          # cycle('ABCD') --> A B C D A B C D A B C D ...
          saved = []
          for element in iterable:
              yield element
              saved.append(element)
          while saved:
              for element in saved:
                    yield element

Note, this member of the toolkit may require significant auxiliary storage
   (depending on the length of the iterable).

.. function:: dropwhile(predicate, iterable)

Make an iterator that drops elements from the iterable as long as the predicate
   is true; afterwards, returns every element.  Note, the iterator does not produce
   *any* output until the predicate first becomes false, so it may have a lengthy
   start-up time.  Roughly equivalent to::

def dropwhile(predicate, iterable):
          # dropwhile(lambda x: x<5, [1,4,6,4,1]) --> 6 4 1
          iterable = iter(iterable)
          for x in iterable:
              if not predicate(x):
                  yield x
                  break
          for x in iterable:
              yield x

.. function:: groupby(iterable[, key])

Make an iterator that returns consecutive keys and groups from the *iterable*.
   The *key* is a function computing a key value for each element.  If not
   specified or is ``None``, *key* defaults to an identity function and returns
   the element unchanged.  Generally, the iterable needs to already be sorted on
   the same key function.

The operation of :func:`groupby` is similar to the ``uniq`` filter in Unix.  It
   generates a break or new group every time the value of the key function changes
   (which is why it is usually necessary to have sorted the data using the same key
   function).  That behavior differs from SQL's GROUP BY which aggregates common
   elements regardless of their input order.

The returned group is itself an iterator that shares the underlying iterable
   with :func:`groupby`.  Because the source is shared, when the :func:`groupby`
   object is advanced, the previous group is no longer visible.  So, if that data
   is needed later, it should be stored as a list::

groups = []
      uniquekeys = []
      data = sorted(data, key=keyfunc)
      for k, g in groupby(data, keyfunc):
          groups.append(list(g))      # Store group iterator as a list
          uniquekeys.append(k)

:func:`groupby` is roughly equivalent to::

class groupby(object):
          # [k for k, g in groupby('AAAABBBCCDAABBB')] --> A B C D A B
          # [list(g) for k, g in groupby('AAAABBBCCD')] --> AAAA BBB CC D
          def __init__(self, iterable, key=None):
              if key is None:
                  key = lambda x: x
              self.keyfunc = key
              self.it = iter(iterable)
              self.tgtkey = self.currkey = self.currvalue = object()
          def __iter__(self):
              return self
          def next(self):
              while self.currkey == self.tgtkey:
                  self.currvalue = next(self.it)    # Exit on StopIteration
                  self.currkey = self.keyfunc(self.currvalue)
              self.tgtkey = self.currkey
              return (self.currkey, self._grouper(self.tgtkey))
          def _grouper(self, tgtkey):
              while self.currkey == tgtkey:
                  yield self.currvalue
                  self.currvalue = next(self.it)    # Exit on StopIteration
                  self.currkey = self.keyfunc(self.currvalue)

.. versionadded:: 2.4

.. function:: ifilter(predicate, iterable)

Make an iterator that filters elements from iterable returning only those for
   which the predicate is ``True``. If *predicate* is ``None``, return the items
   that are true. Roughly equivalent to::

def ifilter(predicate, iterable):
          # ifilter(lambda x: x%2, range(10)) --> 1 3 5 7 9
          if predicate is None:
              predicate = bool
          for x in iterable:
              if predicate(x):
                  yield x

.. function:: ifilterfalse(predicate, iterable)

Make an iterator that filters elements from iterable returning only those for
   which the predicate is ``False``. If *predicate* is ``None``, return the items
   that are false. Roughly equivalent to::

def ifilterfalse(predicate, iterable):
          # ifilterfalse(lambda x: x%2, range(10)) --> 0 2 4 6 8
          if predicate is None:
              predicate = bool
          for x in iterable:
              if not predicate(x):
                  yield x

.. function:: imap(function, *iterables)

Make an iterator that computes the function using arguments from each of the
   iterables.  If *function* is set to ``None``, then :func:`imap` returns the
   arguments as a tuple.  Like :func:`map` but stops when the shortest iterable is
   exhausted instead of filling in ``None`` for shorter iterables.  The reason for
   the difference is that infinite iterator arguments are typically an error for
   :func:`map` (because the output is fully evaluated) but represent a common and
   useful way of supplying arguments to :func:`imap`. Roughly equivalent to::

def imap(function, *iterables):
          # imap(pow, (2,3,10), (5,2,3)) --> 32 9 1000
          iterables = map(iter, iterables)
          while True:
              args = [next(it) for it in iterables]
              if function is None:
                  yield tuple(args)
              else:
                  yield function(*args)

.. function:: islice(iterable, stop)
              islice(iterable, start, stop[, step])

Make an iterator that returns selected elements from the iterable. If *start* is
   non-zero, then elements from the iterable are skipped until start is reached.
   Afterward, elements are returned consecutively unless *step* is set higher than
   one which results in items being skipped.  If *stop* is ``None``, then iteration
   continues until the iterator is exhausted, if at all; otherwise, it stops at the
   specified position.  Unlike regular slicing, :func:`islice` does not support
   negative values for *start*, *stop*, or *step*.  Can be used to extract related
   fields from data where the internal structure has been flattened (for example, a
   multi-line report may list a name field on every third line).  Roughly equivalent to::

def islice(iterable, *args):
          # islice('ABCDEFG', 2) --> A B
          # islice('ABCDEFG', 2, 4) --> C D
          # islice('ABCDEFG', 2, None) --> C D E F G
          # islice('ABCDEFG', 0, None, 2) --> A C E G
          s = slice(*args)
          start, stop, step = s.start or 0, s.stop or sys.maxint, s.step or 1
          it = iter(xrange(start, stop, step)))
          try:
              nexti = next(it)
          except StopIteration:
              # Consume *iterable* up to the *start* position.
              for i, element in izip(xrange(start), iterable):
                  pass
              return
          try:
              for i, element in enumerate(iterable):
                  if i == nexti:
                      yield element
                      nexti = next(it)
          except StopIteration:
              # Consume to *stop*.
              for i, element in izip(xrange(i + 1, stop), iterable):
                  pass

If *start* is ``None``, then iteration starts at zero. If *step* is ``None``,
   then the step defaults to one.

.. versionchanged:: 2.5
      accept ``None`` values for default *start* and *step*.

.. function:: izip(*iterables)

Make an iterator that aggregates elements from each of the iterables. Like
   :func:`zip` except that it returns an iterator instead of a list.  Used for
   lock-step iteration over several iterables at a time.  Roughly equivalent to::

def izip(*iterables):
          # izip('ABCD', 'xy') --> Ax By
          iterators = map(iter, iterables)
          while iterators:
              yield tuple(map(next, iterators))

.. versionchanged:: 2.4
      When no iterables are specified, returns a zero length iterator instead of
      raising a :exc:`TypeError` exception.

The left-to-right evaluation order of the iterables is guaranteed. This
   makes possible an idiom for clustering a data series into n-length groups
   using ``izip(*[iter(s)]*n)``.

:func:`izip` should only be used with unequal length inputs when you don't
   care about trailing, unmatched values from the longer iterables.  If those
   values are important, use :func:`izip_longest` instead.

.. function:: izip_longest(*iterables[, fillvalue])

Make an iterator that aggregates elements from each of the iterables. If the
   iterables are of uneven length, missing values are filled-in with *fillvalue*.
   Iteration continues until the longest iterable is exhausted.  Roughly equivalent to::

class ZipExhausted(Exception):
          pass

def izip_longest(*args, **kwds):
          # izip_longest('ABCD', 'xy', fillvalue='-') --> Ax By C- D-
          fillvalue = kwds.get('fillvalue')
          counter = [len(args) - 1]
          def sentinel():
              if not counter[0]:
                  raise ZipExhausted
              counter[0] -= 1
              yield fillvalue
          fillers = repeat(fillvalue)
          iterators = [chain(it, sentinel(), fillers) for it in args]
          try:
              while iterators:
                  yield tuple(map(next, iterators))
          except ZipExhausted:
              pass

If one of the iterables is potentially infinite, then the
   :func:`izip_longest` function should be wrapped with something that limits
   the number of calls (for example :func:`islice` or :func:`takewhile`).  If
   not specified, *fillvalue* defaults to ``None``.

.. versionadded:: 2.6

.. function:: permutations(iterable[, r])

Return successive *r* length permutations of elements in the *iterable*.

If *r* is not specified or is ``None``, then *r* defaults to the length
   of the *iterable* and all possible full-length permutations
   are generated.

Permutations are emitted in lexicographic sort order.  So, if the
   input *iterable* is sorted, the permutation tuples will be produced
   in sorted order.

Elements are treated as unique based on their position, not on their
   value.  So if the input elements are unique, there will be no repeat
   values in each permutation.

Roughly equivalent to::

def permutations(iterable, r=None):
            # permutations('ABCD', 2) --> AB AC AD BA BC BD CA CB CD DA DB DC
            # permutations(range(3)) --> 012 021 102 120 201 210
            pool = tuple(iterable)
            n = len(pool)
            r = n if r is None else r
            if r > n:
                return
            indices = range(n)
            cycles = range(n, n-r, -1)
            yield tuple(pool[i] for i in indices[:r])
            while n:
                for i in reversed(range(r)):
                    cycles[i] -= 1
                    if cycles[i] == 0:
                        indices[i:] = indices[i+1:] + indices[i:i+1]
                        cycles[i] = n - i
                    else:
                        j = cycles[i]
                        indices[i], indices[-j] = indices[-j], indices[i]
                        yield tuple(pool[i] for i in indices[:r])
                        break
                else:
                    return

The code for :func:`permutations` can be also expressed as a subsequence of
   :func:`product`, filtered to exclude entries with repeated elements (those
   from the same position in the input pool)::

def permutations(iterable, r=None):
            pool = tuple(iterable)
            n = len(pool)
            r = n if r is None else r
            for indices in product(range(n), repeat=r):
                if len(set(indices)) == r:
                    yield tuple(pool[i] for i in indices)

The number of items returned is ``n! / (n-r)!`` when ``0 <= r <= n``
   or zero when ``r > n``.

.. versionadded:: 2.6

.. function:: product(*iterables[, repeat])

Cartesian product of input iterables.

Roughly equivalent to nested for-loops in a generator expression. For example,
   ``product(A, B)`` returns the same as ``((x,y) for x in A for y in B)``.

The nested loops cycle like an odometer with the rightmost element advancing
   on every iteration.  This pattern creates a lexicographic ordering so that if
   the input's iterables are sorted, the product tuples are emitted in sorted
   order.

To compute the product of an iterable with itself, specify the number of
   repetitions with the optional *repeat* keyword argument.  For example,
   ``product(A, repeat=4)`` means the same as ``product(A, A, A, A)``.

This function is roughly equivalent to the following code, except that the
   actual implementation does not build up intermediate results in memory::

def product(*args, **kwds):
           # product('ABCD', 'xy') --> Ax Ay Bx By Cx Cy Dx Dy
           # product(range(2), repeat=3) --> 000 001 010 011 100 101 110 111
           pools = map(tuple, args) * kwds.get('repeat', 1)
           result = [[]]
           for pool in pools:
               result = [x+[y] for x in result for y in pool]
           for prod in result:
               yield tuple(prod)

.. versionadded:: 2.6

.. function:: repeat(object[, times])

Make an iterator that returns *object* over and over again. Runs indefinitely
   unless the *times* argument is specified. Used as argument to :func:`imap` for
   invariant function parameters.  Also used with :func:`izip` to create constant
   fields in a tuple record.  Roughly equivalent to::

def repeat(object, times=None):
          # repeat(10, 3) --> 10 10 10
          if times is None:
              while True:
                  yield object
          else:
              for i in xrange(times):
                  yield object

A common use for *repeat* is to supply a stream of constant values to *imap*
   or *zip*::

>>> list(imap(pow, xrange(10), repeat(2)))
      [0, 1, 4, 9, 16, 25, 36, 49, 64, 81]

.. function:: starmap(function, iterable)

Make an iterator that computes the function using arguments obtained from
   the iterable.  Used instead of :func:`imap` when argument parameters are already
   grouped in tuples from a single iterable (the data has been "pre-zipped").  The
   difference between :func:`imap` and :func:`starmap` parallels the distinction
   between ``function(a,b)`` and ``function(*c)``. Roughly equivalent to::

def starmap(function, iterable):
          # starmap(pow, [(2,5), (3,2), (10,3)]) --> 32 9 1000
          for args in iterable:
              yield function(*args)

.. versionchanged:: 2.6
      Previously, :func:`starmap` required the function arguments to be tuples.
      Now, any iterable is allowed.

.. function:: takewhile(predicate, iterable)

Make an iterator that returns elements from the iterable as long as the
   predicate is true.  Roughly equivalent to::

def takewhile(predicate, iterable):
          # takewhile(lambda x: x<5, [1,4,6,4,1]) --> 1 4
          for x in iterable:
              if predicate(x):
                  yield x
              else:
                  break

.. function:: tee(iterable[, n=2])

Return *n* independent iterators from a single iterable.  Roughly equivalent to::

def tee(iterable, n=2):
            it = iter(iterable)
            deques = [collections.deque() for i in range(n)]
            def gen(mydeque):
                while True:
                    if not mydeque:             # when the local deque is empty
                        newval = next(it)       # fetch a new value and
                        for d in deques:        # load it to all the deques
                            d.append(newval)
                    yield mydeque.popleft()
            return tuple(gen(d) for d in deques)

Once :func:`tee` has made a split, the original *iterable* should not be
   used anywhere else; otherwise, the *iterable* could get advanced without
   the tee objects being informed.

This itertool may require significant auxiliary storage (depending on how
   much temporary data needs to be stored). In general, if one iterator uses
   most or all of the data before another iterator starts, it is faster to use
   :func:`list` instead of :func:`tee`.

.. versionadded:: 2.4

.. _itertools-recipes:

Recipes
-------

This section shows recipes for creating an extended toolset using the existing
itertools as building blocks.

The extended tools offer the same high performance as the underlying toolset.
The superior memory performance is kept by processing elements one at a time
rather than bringing the whole iterable into memory all at once. Code volume is
kept small by linking the tools together in a functional style which helps
eliminate temporary variables.  High speed is retained by preferring
"vectorized" building blocks over the use of for-loops and :term:`generator`\s
which incur interpreter overhead.

.. testcode::

def take(n, iterable):
       "Return first n items of the iterable as a list"
       return list(islice(iterable, n))

def tabulate(function, start=0):
       "Return function(0), function(1), ..."
       return imap(function, count(start))

def consume(iterator, n=None):
       "Advance the iterator n-steps ahead. If n is None, consume entirely."
       # Use functions that consume iterators at C speed.
       if n is None:
           # feed the entire iterator into a zero-length deque
           collections.deque(iterator, maxlen=0)
       else:
           # advance to the empty slice starting at position n
           next(islice(iterator, n, n), None)

def nth(iterable, n, default=None):
       "Returns the nth item or a default value"
       return next(islice(iterable, n, None), default)

def all_equal(iterable):
       "Returns True if all the elements are equal to each other"
       g = groupby(iterable)
       return next(g, True) and not next(g, False)

def quantify(iterable, pred=bool):
       "Count how many times the predicate is true"
       return sum(imap(pred, iterable))

def padnone(iterable):
       """Returns the sequence elements and then returns None indefinitely.

Useful for emulating the behavior of the built-in map() function.
       """
       return chain(iterable, repeat(None))

def ncycles(iterable, n):
       "Returns the sequence elements n times"
       return chain.from_iterable(repeat(tuple(iterable), n))

def dotproduct(vec1, vec2):
       return sum(imap(operator.mul, vec1, vec2))

def flatten(listOfLists):
       "Flatten one level of nesting"
       return chain.from_iterable(listOfLists)

def repeatfunc(func, times=None, *args):
       """Repeat calls to func with specified arguments.

Example:  repeatfunc(random.random)
       """
       if times is None:
           return starmap(func, repeat(args))
       return starmap(func, repeat(args, times))

def pairwise(iterable):
       "s -> (s0,s1), (s1,s2), (s2, s3), ..."
       a, b = tee(iterable)
       next(b, None)
       return izip(a, b)

def grouper(iterable, n, fillvalue=None):
       "Collect data into fixed-length chunks or blocks"
       # grouper('ABCDEFG', 3, 'x') --> ABC DEF Gxx
       args = [iter(iterable)] * n
       return izip_longest(fillvalue=fillvalue, *args)

def roundrobin(*iterables):
       "roundrobin('ABC', 'D', 'EF') --> A D E B F C"
       # Recipe credited to George Sakkis
       pending = len(iterables)
       nexts = cycle(iter(it).next for it in iterables)
       while pending:
           try:
               for next in nexts:
                   yield next()
           except StopIteration:
               pending -= 1
               nexts = cycle(islice(nexts, pending))

def powerset(iterable):
       "powerset([1,2,3]) --> () (1,) (2,) (3,) (1,2) (1,3) (2,3) (1,2,3)"
       s = list(iterable)
       return chain.from_iterable(combinations(s, r) for r in range(len(s)+1))

def unique_everseen(iterable, key=None):
       "List unique elements, preserving order. Remember all elements ever seen."
       # unique_everseen('AAAABBBCCDAABBB') --> A B C D
       # unique_everseen('ABBCcAD', str.lower) --> A B C D
       seen = set()
       seen_add = seen.add
       if key is None:
           for element in ifilterfalse(seen.__contains__, iterable):
               seen_add(element)
               yield element
       else:
           for element in iterable:
               k = key(element)
               if k not in seen:
                   seen_add(k)
                   yield element

def unique_justseen(iterable, key=None):
       "List unique elements, preserving order. Remember only the element just seen."
       # unique_justseen('AAAABBBCCDAABBB') --> A B C D A B
       # unique_justseen('ABBCcAD', str.lower) --> A B C A D
       return imap(next, imap(itemgetter(1), groupby(iterable, key)))

def iter_except(func, exception, first=None):
       """ Call a function repeatedly until an exception is raised.

Converts a call-until-exception interface to an iterator interface.
       Like __builtin__.iter(func, sentinel) but uses an exception instead
       of a sentinel to end the loop.

Examples:
           bsddbiter = iter_except(db.next, bsddb.error, db.first)
           heapiter = iter_except(functools.partial(heappop, h), IndexError)
           dictiter = iter_except(d.popitem, KeyError)
           dequeiter = iter_except(d.popleft, IndexError)
           queueiter = iter_except(q.get_nowait, Queue.Empty)
           setiter = iter_except(s.pop, KeyError)

"""
       try:
           if first is not None:
               yield first()
           while 1:
               yield func()
       except exception:
           pass

def random_product(*args, **kwds):
       "Random selection from itertools.product(*args, **kwds)"
       pools = map(tuple, args) * kwds.get('repeat', 1)
       return tuple(random.choice(pool) for pool in pools)

def random_permutation(iterable, r=None):
       "Random selection from itertools.permutations(iterable, r)"
       pool = tuple(iterable)
       r = len(pool) if r is None else r
       return tuple(random.sample(pool, r))

def random_combination(iterable, r):
       "Random selection from itertools.combinations(iterable, r)"
       pool = tuple(iterable)
       n = len(pool)
       indices = sorted(random.sample(xrange(n), r))
       return tuple(pool[i] for i in indices)

def random_combination_with_replacement(iterable, r):
       "Random selection from itertools.combinations_with_replacement(iterable, r)"
       pool = tuple(iterable)
       n = len(pool)
       indices = sorted(random.randrange(n) for i in xrange(r))
       return tuple(pool[i] for i in indices)

def tee_lookahead(t, i):
       """Inspect the i-th upcomping value from a tee object
          while leaving the tee object at its current position.

Raise an IndexError if the underlying iterator doesn't
          have enough values.

"""
       for value in islice(t.__copy__(), i, None):
           return value
       raise IndexError(i)

Note, many of the above recipes can be optimized by replacing global lookups
with local variables defined as default values.  For example, the
*dotproduct* recipe can be written as::

def dotproduct(vec1, vec2, sum=sum, imap=imap, mul=operator.mul):
       return sum(imap(mul, vec1, vec2))

cmd: