.. _python-built-in-types-and-operations:

.. _`standard_library`: http://docs.python.org/3/library/
.. _`built-in_types`: http://docs.python.org/3/library/stdtypes.html
.. _`numeric_types`: http://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex
.. _`sequence_types`: http://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range
.. _`strings`: http://docs.python.org/3/library/stdtypes.html#text-sequence-type-str
.. _`dictionaries`: http://docs.python.org/3/library/stdtypes.html#mapping-types-dict


.. contents::
    
Download this page as:
    
    - :download:`a commented Python script <types.py>`
    - :download:`a minimal Python script <types_bare.py>`

Python Built-in Types and Operations
====================================

Python supports a number of built-in types and operations. This
tutorial covers the most common types, but information about
additional types is available `here
<http://docs.python.org/library/stdtypes.html>`_



Basic numeric types
-------------------

The basic data numeric types are similar to those found in other
languages, including:

* Integers (``int``)::

    i = 1

* Floating point values (``float``)::

    f = 4.3

* Complex values (``complex``)::

    c = complex(4., -1.)

Manipulating these behaves the way you would expect, so an operation
(``+``, ``-``, ``/``, ``*``, ``**``, etc.) on two values of the same
type produces another value of the same type, while an operation on
two values with different types produces a value of the more
'advanced' type:

* Adding two integers gives an integer:

.. ipython::
    
    In [1]: 1 + 3

* Multiplying two floats gives a float:

.. ipython::
    
    In [1]: 3. * 2.

* Subtracting two complex numbers gives a complex number:

.. ipython::
    
    In [1]: complex(2.,4.) - complex(1.,6.)

* Multiplying an integer with a float gives a float:

.. ipython::
    
    In [1]: 3 * 9.2 # int * float = float

* Multiplying a float with a complex number gives a complex number:

.. ipython::
    
    In [1]: 2. * complex(-1.,3.) # float * complex = complex

* Multiplying an integer and a complex number gives a complex number:

.. ipython::
    
    In [1]: 8 * complex(-3.3,1) # int * comples = comples

However, there is one case where this happens but is not desirable,
and that you should be aware of, which is the division of two integer
numbers:

.. ipython::
    
    In [1]: 3 / 2

This is behavior is widely regarded as a design mistake and Python 3.x
has been fixed to behave as you would expect (more on Python 3.x
later). A way to prevent this is to cast at least one of the integers
in the division to a ``float``

.. ipython::
    
    In [1]: 3 / float(2)

or

.. ipython::
    
    In [1]: 3 / 2.
    
.. raw:: html

   <p class="flip0">Solving the design mistake in Python 2.x (Click to Show/Hide)</p> <div class="panel0">
 
At the top of a script or in the beginning of your session, you can
import the *future* definition of the division operator. Note that ``/``
means normal division, while ``//`` means integer division. In Python
2.x, the two are equal for integers:
  

.. ipython::   
    
    In [1]: 3/2
    
    In [1]: 3//2
    
    In [1]: from __future__ import division

    In [1]: 3/2
    
    In [1]: 3//2
    


.. raw:: html

   </div>    

Lists, tuples, and sets
-----------------------

There are two types of sequences that appear similar at first glance,
both of which can contain inhomogeneous data types:

* Lists (``list``):
    
    .. ipython::
        
        In [1]: l = [4, 5.5, "spam"]
        
        In [1]: l[0]
        
        In [1]: l[1]
        
        In [1]: l[2]

* Tuples (``tuple``):
    
    .. ipython::
        
        In [1]: t = (4, 5.5, "spam")
        
        In [1]: t[0]
        
        In [1]: t[1]
        
        In [1]: t[2]

.. warning::

    **Indexing starts at 0** (as in C or IDL), not at 1 (as in Fortran or Matlab)!

We can obtain sublists of regularly-spaced elements in a list or tuple
by 'slicing:
    
    .. ipython::
        
        In [1]: l = [1, 2, 3, 4, 5]
        
        In [1]: l[2:4]

Slicing syntax is `l[start:stop:stride]`.  All the slicing parameters
are optional:
    
    .. ipython::
        
        In [1]: l[3:]

        In [1]: l[:3]
        
        In [1]: l[::2]

.. Warning::

    Note that ``l[start:stop]`` contains the elements with indices
    ``i`` such that ``start<= i < stop`` (``i`` ranging from ``start``
    to ``stop-1``). Therefore, ``l[start:stop]`` has ``(stop-start)``
    elements.

We can also use negative numbers when slicing. These count from the
**end** of the sequence:
    
    .. ipython::
        
        In [1]: l[-1]
        
        In [1]: l[-2:]

Using a negative step moves from higher to lower indices. For example,
to reverse `l`:
    
    .. ipython::
        
        In [1]: r = l[::-1]
        
        In [1]: r

Lists are *mutable* objects and can be modified:
    
    .. ipython::
        
        In [1]: l[0] = 28
        
        In [1]: l
        
        In [1]: l[2:4] = [3, 8]
        
        In [1]: l

The elements of a list may have different types:
    
    .. ipython::
        
        In [1]: l = [3, 2, 'hello']
        
        In [1]: l
        
        In [1]: l[1], l[2]

Python offers a large number of functions to modify lists, or query
them. Here are a few examples; for more details, see
http://docs.python.org/tutorial/datastructures.html#more-on-lists

Add and remove elements:
    
    .. ipython::
        
        In [1]: l = [1, 2, 3, 4, 5]
        
        In [1]: l.append(6)
    
        In [1]: l
        
        In [1]: l.pop()
    
        In [1]: l
        
        In [1]: l.extend([6, 7]) # extend l, in-place
        
        In [1]: l

Concatenate and repeat lists:
    
    .. ipython::
        
        In [1]: r + l
    
        In [1]: 2 * r

Sort r (in-place):
    
    .. ipython::
        
        In [1]: r.sort()
    
        In [1]: r


.. Note:: **Methods and Object-Oriented Programming**

    - The notation ``r.method()`` (``r.sort(), r.append(3), l.pop()``)
      is an example of object-oriented programming (OOP). Being a
      ``list``, the object `r` owns the *method* `function` that is
      called using the notation **.**. No further knowledge of OOP than
      understanding the notation **.** is necessary for going through
      this tutorial.
      
    - Most things in Python are objects! Every constant, variable, or function
      in Python is actually an object with a type and associated attributes and
      methods. An *attribute* a property of the object that you get or set by
      giving the <object_name> + dot + <attribute_name>, for example
      ``img.shape``. A *method* is a function that the object provides,
      for example ``img.argmax(axis=0)`` or ``img.min()``.
      
    - In the IPython shell, we can take advantage of objects via *tab completion*::
        
        >>> r.<TAB>
        r.append   r.count    r.extend   r.index    r.insert   r.pop      r.remove   r.reverse  r.sort
    
    - Most methods are documented so that you can ask for help::
        
        >>> help(r.remove)
        Help on built-in function remove:

        remove(...)
            L.remove(value) -- remove first occurrence of value.
            Raises ValueError if the value is not present.

    
    

The difference between lists and tuples is that lists are mutable, and
tuples are immutable:

    .. ipython::
        
        In [1]: l = [1, 2, 3]
        
        In [1]: l.append('egg')  # For a full list of methods, type l. then press TAB!
        
        In [1]: l.insert(3, 'spam')
    
        In [1]: l

        In [1]: t = (1, 2, 3)
        
        In [1]: t[0] = 3

There are reasons why tuples are a useful feature (faster and
`hashable <http://docs.python.org/glossary.html#term-hashable>`_ are
the two main ones), but for now, it's enough for you to know there is
such a difference.

Sets (``set``) are a third type of sequence which you can make from a
tuple or a list:

    .. ipython::
        
        In [1]: set([1, 2, 3, 2, 'spam', 'egg', 'spam'])    

Note that duplicate items have been removed. This is the mathematical
definition of a set, i.e. a collection of *distinct* objects. The
order of the objects is arbitrary (order is not preserved). Various
operators can be used to represent set operations:

    .. ipython::
        
        In [1]: set([1,2,3]) - set([3,4])

        In [1]: set([1,2,3]) & set([3,4])

        In [1]: set([1,2,3]) | set([3,4])

If you want to test whether a single item is member of a very large
collection of items, it can be faster to use a set rather than a list
or tuple:

    .. ipython::
        
        In [1]: 'a' in set(['a', 'b', 'c', 'd', 'e', 'f'])

For collections of numerical data that all have the same type, it is
often **more efficient** to use the ``array`` type provided by the
``numpy`` module. A NumPy array is a chunk of memory containing
fixed-sized items.  With NumPy arrays, operations on elements can be
faster because elements are regularly spaced in memory and more
operations are perfomed through specialized C functions instead of
Python loops.


Strings
-------

Strings (``str``) will be familiar from other programming language:

    .. ipython::
        
        In [1]: s = "Spam egg spam spam"

You can use either single quotes (``'``), double quotes (``"``), or
triple quotes (``'''``) to enclose a string (the last one is used for
multi-line strings). To include single or double quotes inside a
string, you can either use the opposite quote to enclose the string:

    .. ipython::
        
        In [1]: "I'm"

        In [1]: '"hello"'

or you can *escape* them:

    .. ipython::
        
        In [1]: 'I\'m'

        In [1]: "\"hello\""

Strings are sequences like lists. Hence they can be indexed and
sliced, using the same syntax and rules.

Indexing:

    .. ipython::
        
        In [1]: s = "hello"
        
        In [1]: s[0]
        
        In [1]: s[1]
    
        In [1]: s[-1]


(Remember that negative indices correspond to counting from the right
end.)

Slicing:

    .. ipython::
        
        In [1]: s = "hello, world!"
    
        In [1]: s[3:6] # 3rd to 6th (excluded) elements: elements 3, 4, 5
        
        In [1]: s[2:10:2] # Syntax: a[start:stop:step]
        
        In [1]: s[::3] # every three characters, from beginning to end 

Note that strings are immutable (like tuples), that is you cannot
change the value of certain characters without creating a new string:

    .. ipython::
        
        In [1]: s[5] = 'r'
    
        In [1]: s.replace('l', 'z', 1)
    
        In [1]: s.replace('l', 'z')
    
As for lists, and tuples, concatenation is done with ``+``:

    .. ipython::
        
        In [1]: "hello," + " " + "world!"

Strings have many methods associated with them like
``.replace()`` used above. Here are a few more examples:

    .. ipython::
        
        In [1]: s = "Spam egg spam spam"
        
        In [1]: s.upper() # An uppercase version of the string

        In [1]: s.index('egg') # An integer giving the position of the sub-string
        
        In [1]: s.split() # A list of strings
        
       
And finally, strings have a ``format`` method, which allows nice string formatting (see `the official docs <http://docs.python.org/3/library/string.html#format-string-syntax>`_ for a full overview).
    
    .. ipython:: 
        
        In [1]: print('{:8.3f}'.format(3.14159265))
        
        In [1]: print('{:.10f}'.format(3.14159265))
        
        In [1]: print('{:.6e}'.format(3.14159265))
        
        In [1]: print('{:04d}'.format(3))
        
        In [1]: print('{:g}'.format(3.14159265))
        
        In [1]: print('{:g}'.format(0))
        
        In [1]: print('{:g}'.format(10000000000000000000000))
       
       
       
Dictionaries
------------

One of the remaining types are dictionaries (``dict``) which you can
think of as look-up tables:

    .. ipython::
        
        In [1]: d = {'name':'m31', 'ra':10.68, 'dec':41.27}
        
        In [1]: d['name']
    
        In [1]: d['flux'] = 4.5
    
        In [1]: d
        
        In [1]: list(d.keys())
        
        In [1]: list(d.values())
        
        In [1]: 'ra' in d
    


**See also**

.. _`standard_library`: http://docs.python.org/3/library/
.. _`built-in_types`: http://docs.python.org/3/library/stdtypes.html
.. _`numeric_types`: http://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex
.. _`sequence_types`: http://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range
.. _`strings`: http://docs.python.org/3/library/stdtypes.html#text-sequence-type-str
.. _`dictionaries`: http://docs.python.org/3/library/stdtypes.html#mapping-types-dict

=============================== ==================================================================
`built-in_types`_               Overview of all built-in types
`numeric_types`_                int, float, complex
`sequence_types`_               list, tuple, range
`strings`_                      str
`dictionaries`_                 dict
=============================== ==================================================================