# .. _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:
# 

1 + 3

# 
# * Multiplying two floats gives a float:
# 

3. * 2.

# 
# * Subtracting two complex numbers gives a complex number:
# 

complex(2.,4.) - complex(1.,6.)

# 
# * Multiplying an integer with a float gives a float:
# 

3 * 9.2 # int * float = float

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

2. * complex(-1.,3.) # float * complex = complex

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

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:
# 

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``
# 

3 / float(2)

# 
# or
# 

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:
#   
# 

3/2
3//2
#from __future__ import division (this does not work in the body of a script, it needs to be at the top!)

# 
#     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``):
#     

l = [4, 5.5, "spam"]
l[0]
l[1]
l[2]

# * Tuples (``tuple``):
#     

t = (4, 5.5, "spam")
t[0]
t[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:
#     

l = [1, 2, 3, 4, 5]
l[2:4]

# Slicing syntax is `l[start:stop:stride]`.  All the slicing parameters
# are optional:
#     

l[3:]
l[:3]
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:
#     

l[-1]
l[-2:]

# Using a negative step moves from higher to lower indices. For example,
# to reverse `l`:
#     

r = l[::-1]
r

# Lists are *mutable* objects and can be modified:
#     

l[0] = 28
l
l[2:4] = [3, 8]
l

# The elements of a list may have different types:
#     

l = [3, 2, 'hello']
l
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:
#     

l = [1, 2, 3, 4, 5]
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:
#     

r + l

#     
#         In [1]: 2 * r
# 
# Sort r (in-place):
#     

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:
# 

l = [1, 2, 3]
l.append('egg')  # For a full list of methods, type l. then press TAB!
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:
# 

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:
# 

set([1,2,3]) - set([3,4])
set([1,2,3]) & set([3,4])
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:
# 

'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:
# 

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:
# 

"I'm"
'"hello"'

# or you can *escape* them:
# 

'I\'m'
"\"hello\""

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

s = "hello"
s[0]
s[1]

#     
#         In [1]: s[-1]
# 
# 
# (Remember that negative indices correspond to counting from the right
# end.)
# 
# Slicing:
# 

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:
# 

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 ``+``:
# 

"hello," + " " + "world!"

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

s = "Spam egg spam spam"
s.upper() # An uppercase version of the string
s.index('egg') # An integer giving the position of the sub-string
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).
#     

print('{:8.3f}'.format(3.14159265))
print('{:.10f}'.format(3.14159265))
print('{:.6e}'.format(3.14159265))
print('{:04d}'.format(3))
print('{:g}'.format(3.14159265))
print('{:g}'.format(0))
print('{:g}'.format(10000000000000000000000))

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

d = {'name':'m31', 'ra':10.68, 'dec':41.27}
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
# =============================== ==================================================================