=============
Python: Tuple
=============

Tuples are **immutable** lists.

In order to define a tuple, use this syntax::

    binding_partners = (
        "BIOGRID:112315",
        "BIOGRID:108607"  # no comma
    )

Leaving an additional comma after the last element also works::

    binding_partners = (
        "BIOGRID:112315",
        "BIOGRID:108607", # this comma makes no difference
    )

Tuples should be used instead of lists whenever mutability is an issue, for
instance as dictionary keys.

**Example**. Let's create a bunch of different tuples::

    # A tuple of integers
    integers = (1, 2, 3, 1)

    # A tuple of strings
    uniprot_proteins = ("Y08501", "Q95747")

    # A tuple of heterogeneous objects
    things = ("Y08501", 0.13, "Q95747", 0.96)

    # A tuple of tuples
    two_level_tuple = (
        ("Y08501", 120, 520),
        ("Q95747", 550, 920),
    )

**Example**. Empty and length-one tuples are a bit weird. I will not
explain how to create empty tuples, they are very rare (and not really
useful).

But let's assume for the sake of illustration that we need to create
a tuple with just one element, say the integer ``0``. This does not work::

    tuple = (0)
    print tuple
    print type(tuple)   # not a tuple!

The reason is that ``(0)`` is interpreted by Python as an *arithmetical
expression*. Indeed, this is what the syntax means: an integer within a pair of
brackets.

In order to define such a one-element tuple, write::

    tuple = (0,)
    print tuple
    print type(tuple)   # it's a tuple!

Now the ambiguity is gone: the comma ``,`` in there makes it clear to Python
that we want to create a tuple -- except that it contains only one element.

|

Operators
---------

Most list operators can be used with tuples as well. Of course, since tuples
are **immutable**, operators that change the value of lists (like the
assignment operator) do *not* carry over to tuples.

========= =================== ====================================================
Returns   Operator            Meaning
========= =================== ====================================================
``int``   ``len(tuple)``      Compute the length of a tuple
``tuple`` ``tuple + tuple``   Concatenate two tuples
``tuple`` ``tuple * int``     Replicate a tuple
``bool``  ``object in tuple`` Check whether an element appears in a tuple
``tuple`` ``tuple[int:int]``  Extract a sub-tuple
========= =================== ====================================================

****

**Example**. Let's create a tuple with mixed object types::

    protein_info = ("2B0Q", "phosphotransferase", "PF03881")

It holds information about a given protein (PDB identifier 2B0Q). We can
access the various elements as if it were a list::

    protein_id = protein_info[0]
    print protein_id

    protein_name = protein_info[1]
    print protein_name

However, we can **not** modify the tuple in any way::

    >>> protein_info[0] = "1A3A"
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: 'tuple' object does not support item assignment

****

|

Methods
-------

======== ====================== =====================================================
Returns  Method                 Meaning
======== ====================== =====================================================
``int``  ``list.index(object)`` Return the index of the first occurrence of an object
``int``  ``list.count(object)`` Count the number of occurrences of an object
======== ====================== =====================================================

These are identical to their list counterparts.

|

List-Tuple Conversion
---------------------

In some cases you want to modify a tuple, but you can't. In other cases you
want to use a list as a key in a dictionary, but you can't.

The tricks is to convert between tuples and lists as needed. In order to
convert between the two, use the ``tuple()`` and ``list()`` functions::

    l = range(10)
    print l, type(l)

    t = tuple(l)
    print t, type(t)

    l = list(t)
    print l, type(l)

****

**Example**. We want to modify a given tuple::

    t = ("I", "am", "a", "tuple")
    print t

Let's proceed as follows::

    l = list(t)
    l.insert(2, "pretty")
    t2 = tuple(l)

    print t
    print t2

Of course, we did **not** modify the original tuple; rather, we created
a new tuple from an intermediate list.