# Python Programming/Classes

Classes are a way of aggregating similar data and functions. A class is
basically a scope inside which various code (especially function
definitions) is executed, and the locals to this scope become
*attributes* of the class, and of any objects constructed by this class.
An object constructed by a class is called an *instance* of that class.

### Overview

Classes in Python at a glance:

``` python
import math
class MyComplex:
  """A complex number"""       # Class documentation
  classvar = 0.0               # A class attribute, not an instance one
  def phase(self):             # A method
    return math.atan2(self.imaginary, self.real)
  def __init__(self):          # A constructor
    """A constructor"""
    self.real = 0.0            # An instance attribute
    self.imaginary = 0.0
c1 = MyComplex()
c1.real = 3.14                 # No access protection
c1.imaginary = 2.71
phase = c1.phase()             # Method call
c1.undeclared = 9.99           # Add an instance attribute
del c1.undeclared              # Delete an instance attribute

print(vars(c1))                # Attributes as a dictionary
vars(c1)["undeclared2"] = 7.77 # Write access to an attribute
print(c1.undeclared2)          # 7.77, indeed

MyComplex.classvar = 1         # Class attribute access
print(c1.classvar == 1)        # True; class attribute access, not an instance one
print("classvar" in vars(c1))  # False
c1.classvar = -1               # An instance attribute overshadowing the class one
MyComplex.classvar = 2         # Class attribute access
print(c1.classvar == -1)       # True; instance attribute access
print("classvar" in vars(c1))  # True

class MyComplex2(MyComplex):   # Class derivation or inheritance
  def __init__(self, re = 0, im = 0):
    self.real = re             # A constructor with multiple arguments with defaults
    self.imaginary = im
  def phase(self):
    print("Derived phase")
    return MyComplex.phase(self) # Call to a base class; "super"
c3 = MyComplex2()
c4 = MyComplex2(1, 1)
c4.phase()                     # Call to the method in the derived class

class Record: pass             # Class as a record/struct with arbitrary attributes
record = Record()
record.name = "Joe"
record.surname = "Hoe"
```

### Defining a Class

To define a class, use the following format:

``` python
class ClassName:
    "Here is an explanation about your class"
    pass
```

The capitalization in this class definition is the convention, but is
not required by the language. It\'s usually good to add at least a short
explanation of what your class is supposed to do. The pass statement in
the code above is just to say to the python interpreter just go on and
do nothing. You can remove it as soon as you are adding your first
statement.

### Instance Construction

The class is a callable object that constructs an instance of the class
when called. Let\'s say we create a class Foo.

``` python
class Foo:
    "Foo is our new toy."
    pass
```

To construct an instance of the class, Foo, \"call\" the class object:

``` python
f = Foo()
```

This constructs an instance of class Foo and creates a reference to it
in f.

### Class Members

In order to access the member of an instance of a class, use the syntax
`<class instance>`{=html}.`<member>`{=html}. It is also possible to
access the members of the class definition with
`<class name>`{=html}.`<member>`{=html}.

#### Methods

A method is a function within a class. The first argument (methods must
always take at least one argument) is always the instance of the class
on which the function is invoked. For example

``` python
>>> class Foo:
...     def setx(self, x):
...         self.x = x
...     def bar(self):
...         print(self.x)
```

If this code were executed, nothing would happen, at least until an
instance of Foo were constructed, and then bar were called on that
instance.

##### Why a mandatory argument?

In a normal function, if you were to set a variable, such as
`test = 23`, you could not access the test variable. Typing `test` would
say it is not defined. This is true in class functions unless they use
the `self` variable.

Basically, in the previous example, if we were to remove self.x,
function bar could not do anything because it could not access x. The x
in setx() would disappear. The self argument saves the variable into the
class\'s \"shared variables\" database.

##### Why self?

You do not need to use self. However, it is a norm to use self.

#### Invoking Methods

Calling a method is much like calling a function, but instead of passing
the instance as the first parameter like the list of formal parameters
suggests, use the function as an attribute of the instance.

``` python
>>> f = Foo()
>>> f.setx(5)
>>> f.bar()
```

This will output

`5`

It is possible to call the method on an arbitrary object, by using it as
an attribute of the defining class instead of an instance of that class,
like so:

``` python
>>> Foo.setx(f,5)
>>> Foo.bar(f)
```

This will have the same output.

#### Dynamic Class Structure

As shown by the method setx above, the members of a Python class can
change during runtime, not just their values, unlike classes in
languages like C++ or Java. We can even delete f.x after running the
code above.

``` python
>>> del f.x
>>> f.bar()
```

`Traceback (most recent call last):`\
`  File "``<stdin>`{=html}`", line 1, in ?`\
`  File "``<stdin>`{=html}`", line 5, in bar`\
`AttributeError: Foo instance has no attribute 'x'`

Another effect of this is that we can change the definition of the Foo
class during program execution. In the code below, we create a member of
the Foo class definition named y. If we then create a new instance of
Foo, it will now have this new member.

``` python
>>> Foo.y = 10
>>> g = Foo()
>>> g.y
10
```

##### Viewing Class Dictionaries

At the heart of all this is a
dictionary that can be
accessed by \"vars(ClassName)\"

``` python
>>> vars(g)
{}
```

At first, this output makes no sense. We just saw that g had the member
y, so why isn\'t it in the member dictionary? If you remember, though,
we put y in the class definition, Foo, not g.

``` python
>>> vars(Foo)
{'y': 10, 'bar': <function bar at 0x4d6a3c>, '__module__': '__main__',
 'setx': <function setx at 0x4d6a04>, '__doc__': None}
```

And there we have all the members of the Foo class definition. When
Python checks for g.member, it first checks g\'s vars dictionary for
\"member,\" then Foo. If we create a new member of g, it will be added
to g\'s dictionary, but not Foo\'s.

``` python
>>> g.setx(5)
>>> vars(g)
{'x': 5}
```

Note that if we now assign a value to g.y, we are not assigning that
value to Foo.y. Foo.y will still be 10, but g.y will now override Foo.y

``` python
>>> g.y = 9
>>> vars(g)
{'y': 9, 'x': 5}
>>> vars(Foo)
{'y': 10, 'bar': <function bar at 0x4d6a3c>, '__module__': '__main__',
 'setx': <function setx at 0x4d6a04>, '__doc__': None}
```

Sure enough, if we check the values:

``` python
>>> g.y
9
>>> Foo.y
10
```

Note that f.y will also be 10, as Python won\'t find \'y\' in vars(f),
so it will get the value of \'y\' from vars(Foo).

Some may have also noticed that the methods in Foo appear in the class
dictionary along with the x and y. If you remember from the section on
lambda
functions,
we can treat functions just like variables. This means that we can
assign methods to a class during runtime in the same way we assigned
variables. If you do this, though, remember that if we call a method of
a class instance, the first parameter passed to the method will always
be the class instance itself.

##### Changing Class Dictionaries

We can also access the members dictionary of a class using the
\_\_dict\_\_ member of the class.

``` python
>>> g.__dict__
{'y': 9, 'x': 5}
```

If we add, remove, or change key-value pairs from g.\_\_dict\_\_, this
has the same effect as if we had made those changes to the members of g.

``` python
>>> g.__dict__['z'] = -4
>>> g.z
-4
```

### Why use classes?

Classes are special due to the fact once an instance is made, the
instance is independent of all other instances. I could have two
instances, each with a different x value, and they will not affect the
other\'s x.

``` python
f = Foo()
f.setx(324)
f.boo()
g = Foo()
g.setx(100)
g.boo()
```

`f.boo()` and `g.boo()` will print different values.

### New Style Classes

New style classes were introduced in python 2.2. A new-style class is a
class that has a built-in as its base, most commonly object. At a low
level, a major difference between old and new classes is their type. Old
class instances were all of type `instance`. New style class instances
will return the same thing as x.\_\_class\_\_ for their type. This puts
user defined classes on a level playing field with built-ins.
Old/Classic classes are slated to disappear in Python 3. With this in
mind all development should use new style classes. New Style classes
also add constructs like properties and static methods familiar to Java
programmers.

Old/Classic Class

``` python
>>> class ClassicFoo:
...     def __init__(self):
...         pass
```

New Style Class

``` python
>>> class NewStyleFoo(object):
...     def __init__(self):
...         pass
```

#### Properties

Properties are attributes with getter and setter methods.

``` python
>>> class SpamWithProperties(object):
...     def __init__(self):
...         self.__egg = "MyEgg"
...     def get_egg(self):
...         return self.__egg
...     def set_egg(self, egg):
...         self.__egg = egg
...     egg = property(get_egg, set_egg)

>>> sp = SpamWithProperties()
>>> sp.egg
'MyEgg'
>>> sp.egg = "Eggs With Spam"
>>> sp.egg
'Eggs With Spam'
>>>
```

and since Python 2.6, with \@property decorator

``` python
>>> class SpamWithProperties(object):
...     def __init__(self):
...         self.__egg = "MyEgg"
...     @property
...     def egg(self):
...         return self.__egg
...     @egg.setter
...     def egg(self, egg):
...         self.__egg = egg
```

#### Static Methods

Static methods in Python are just like their counterparts in C++ or
Java. Static methods have no \"self\" argument and don\'t require you to
instantiate the class before using them. They can be defined using
staticmethod()

``` python
>>> class StaticSpam(object):
...     def StaticNoSpam():
...         print("You can't have have the spam, spam, eggs and spam without any spam... that's disgusting")
...     NoSpam = staticmethod(StaticNoSpam)

>>> StaticSpam.NoSpam()
You can't have have the spam, spam, eggs and spam without any spam... that's disgusting
```

They can also be defined using the function decorator \@staticmethod.

``` python
>>> class StaticSpam(object):
...     @staticmethod
...     def StaticNoSpam():
...         print("You can't have have the spam, spam, eggs and spam without any spam... that's disgusting")
```

### Inheritance

Like all object oriented languages, Python provides support for
inheritance. Inheritance is a simple concept by which a class can extend
the facilities of another class, or in Python\'s case, multiple other
classes. Use the following format for this:

``` python
class ClassName(BaseClass1, BaseClass2, BaseClass3,...):
    ...
```

ClassName is what is known as the derived class, that is, derived from
the base classes. The derived class will then have all the members of
its base classes. If a method is defined in the derived class and in the
base class, the member in the derived class will override the one in the
base class. In order to use the method defined in the base class, it is
necessary to call the method as an attribute on the defining class, as
in Foo.setx(f,5) above:

``` python
>>> class Foo:
...     def bar(self):
...         print("I'm doing Foo.bar()")
...     x = 10
...
>>> class Bar(Foo):
...     def bar(self):
...         print("I'm doing Bar.bar()")
...         Foo.bar(self)
...     y = 9
...
>>> g = Bar()
>>> Bar.bar(g)
I'm doing Bar.bar()
I'm doing Foo.bar()
>>> g.y
9
>>> g.x
10
```

Once again, we can see what\'s going on under the hood by looking at the
class dictionaries.

``` python
>>> vars(g)
{}
>>> vars(Bar)
{'y': 9, '__module__': '__main__', 'bar': <function bar at 0x4d6a04>,
 '__doc__': None}
>>> vars(Foo)
{'x': 10, '__module__': '__main__', 'bar': <function bar at 0x4d6994>,
 '__doc__': None}
```

When we call g.x, it first looks in the vars(g) dictionary, as usual.
Also as above, it checks vars(Bar) next, since g is an instance of Bar.
However, thanks to inheritance, Python will check vars(Foo) if it
doesn\'t find x in vars(Bar).

### Multiple inheritance

As shown in section #Inheritance, a class can
be derived from multiple classes:

``` python
class ClassName(BaseClass1, BaseClass2, BaseClass3):
    pass
```

A tricky part about multiple inheritance is method resolution: upon a
method call, if the method name is available from multiple base classes
or their base classes, which base class method should be called.

The method resolution order depends on whether the class is an old-style
class or a new-style class. For old-style classes, derived classes are
considered from left to right, and base classes of base classes are
considered before moving to the right. Thus, above, BaseClass1 is
considered first, and if method is not found there, the base classes of
BaseClass1 are considered. If that fails, BaseClass2 is considered, then
its base classes, and so on. For new-style classes, see the Python
documentation online.

Links:

-   9.5.1. Multiple
    Inheritance,
    docs.python.org
-   The Python 2.3 Method Resolution
    Order,
    python.org

### Special Methods

There are a number of methods which have reserved names which are used
for special purposes like mimicking numerical or container operations,
among other things. All of these names begin and end with two
underscores. It is convention that methods beginning with a single
underscore are \'private\' to the scope they are introduced within.

#### Initialization and Deletion

##### \_\_init\_\_

One of these purposes is constructing an instance, and the special name
for this is \'\_\_init\_\_\'. \_\_init\_\_() is called before an
instance is returned (it is not necessary to return the instance
manually). As an example,

``` python
class A:
    def __init__(self):
        print('A.__init__()')
a = A()
```

outputs

`A.__init__()`

\_\_init\_\_() can take arguments, in which case it is necessary to pass
arguments to the class in order to create an instance. For example,

``` python
class Foo:
    def __init__ (self, printme):
        print(printme)
foo = Foo('Hi!')
```

outputs

`Hi!`

Here is an example showing the difference between using \_\_init\_\_()
and not using \_\_init\_\_():

``` python
class Foo:
    def __init__ (self, x):
         print(x)
foo = Foo('Hi!')
class Foo2:
    def setx(self, x):
        print(x)
f = Foo2()
Foo2.setx(f,'Hi!')
```

outputs

`Hi!`\
`Hi!`

##### \_\_del\_\_

Similarly, \'\_\_del\_\_\' is called when an instance is destroyed; e.g.
when it is no longer referenced.

##### \_\_enter\_\_ and \_\_exit\_\_

These methods are also a constructor and a destructor but they\'re only
executed when the class is instantiated with `with`. Example:

``` python
class ConstructorsDestructors:
    def __init__(self):
        print('init')

    def __del__(self):
        print('del')

    def __enter__(self):
        print('enter')

    def __exit__(self, exc_type, exc_value, traceback):
        print('exit')

with ConstructorsDestructors():
    pass
```

`init`\
`enter`\
`exit`\
`del`

##### \_\_new\_\_

constructor.

#### Representation

+----------------------------------+---------------------------------:+
| ##### \_\_str\_\_       |   Function          Operator     |
|                                  |   ---------                      |
| Converting an object to a        | -------- ----------------------- |
| string, as with the print        |   \_\_str\_\_       str(A)       |
| statement or with the str()      |   \_\_repr\_\_      repr(A)      |
| conversion function, can be      |   \_\_uni                        |
| overridden by overriding         | code\_\_   unicode(x) (2.x only) |
| \_\_str\_\_. Usually,            |                                  |
| \_\_str\_\_ returns a formatted  |   : String Representation        |
| version of the objects content.  |   Override Functions             |
| This will NOT usually be         |                                  |
| something that can be executed.  |                                  |
|                                  |                                  |
| For example:                     |                                  |
|                                  |                                  |
| ``` python                       |                                  |
| class Bar:                       |                                  |
|                                  |                                  |
|    def __init__ (self, iamthis): |                                  |
|         self.iamthis = iamthis   |                                  |
|     def __str__ (self):          |                                  |
|         return self.iamthis      |                                  |
| bar = Bar('apple')               |                                  |
| print(bar)                       |                                  |
| ```                              |                                  |
|                                  |                                  |
| outputs                          |                                  |
|                                  |                                  |
| `apple`                          |                                  |
|                                  |                                  |
| ##### \_\_repr\_\_     |                                  |
|                                  |                                  |
| This function is much like       |                                  |
| \_\_str\_\_(). If \_\_str\_\_ is |                                  |
| not present but this one is,     |                                  |
| this function\'s output is used  |                                  |
| instead for printing.            |                                  |
| \_\_repr\_\_ is used to return a |                                  |
| representation of the object in  |                                  |
| string form. In general, it can  |                                  |
| be executed to get back the      |                                  |
| original object.                 |                                  |
|                                  |                                  |
| For example:                     |                                  |
|                                  |                                  |
| ``` python                       |                                  |
| class Bar:                       |                                  |
|                                  |                                  |
|    def __init__ (self, iamthis): |                                  |
|         self.iamthis = iamthis   |                                  |
|     def __repr__(self):          |                                  |
|         r                        |                                  |
| eturn "Bar('%s')" % self.iamthis |                                  |
| bar = Bar('apple')               |                                  |
| bar                              |                                  |
| ```                              |                                  |
|                                  |                                  |
| outputs (note the difference: it |                                  |
| may not be necessary to put it   |                                  |
| inside a print, however in       |                                  |
| Python 2.7 it does)              |                                  |
|                                  |                                  |
| `Bar('apple')`                   |                                  |
+----------------------------------+----------------------------------+

#### Attributes

+----------------------------------+---------------------------------:+
| ##                               |   Function                       |
| ### \_\_setattr\_\_ |   Indirect form      Direct Form |
|                                  |   -----------------              |
| This is the function which is in | ------------------ ------------- |
| charge of setting attributes of  |   \_\_geta                       |
| a class. It is provided with the | ttr\_\_   getattr(A, B)      A.B |
| name and value of the variables  |   \_\_setattr\                   |
| being assigned. Each class, of   | _\_   setattr(A, B, C)   A.B = C |
| course, comes with a default     |   \_\_delattr\                   |
| \_\_setattr\_\_ which simply     | _\_   delattr(A, B)      del A.B |
| sets the value of the variable,  |                                  |
| but we can override it.          |   : Attribute Override Functions |
|                                  |                                  |
| ``` python                       |                                  |
| >>> class Unchangable:           |                                  |
| ...    def                       |                                  |
|  __setattr__(self, name, value): |                                  |
| ...        print("Nice try")     |                                  |
| ...                              |                                  |
| >>> u = Unchangable()            |                                  |
| >>> u.x = 9                      |                                  |
| Nice try                         |                                  |
| >>> u.x                          |                                  |
| ```                              |                                  |
|                                  |                                  |
| `Trac                            |                                  |
| eback (most recent call last):`\ |                                  |
| `  File "``<                     |                                  |
| stdin>`{=html}`", line 1, in ?`\ |                                  |
| `AttributeError: Unchangabl      |                                  |
| e instance has no attribute 'x'` |                                  |
|                                  |                                  |
| #####                            |                                  |
|  \_\_getattr\_\_\_ |                                  |
|                                  |                                  |
| Similar to \_\_setattr\_\_,      |                                  |
| except this function is called   |                                  |
| when we try to access a class    |                                  |
| member, and the default simply   |                                  |
| returns the value.               |                                  |
|                                  |                                  |
| ``` python                       |                                  |
| >>> class HiddenMembers:         |                                  |
| ...                              |                                  |
|     def __getattr__(self, name): |                                  |
| ...         retur                |                                  |
| n "You don't get to see " + name |                                  |
| ...                              |                                  |
| >>> h = HiddenMembers()          |                                  |
| >>> h.anything                   |                                  |
| "You don't get to see anything"  |                                  |
| ```                              |                                  |
|                                  |                                  |
| ##                               |                                  |
| ### \_\_delattr\_\_ |                                  |
|                                  |                                  |
| This function is called to       |                                  |
| delete an attribute.             |                                  |
|                                  |                                  |
| ``` python                       |                                  |
| >>> class Permanent:             |                                  |
| ...                              |                                  |
|     def __delattr__(self, name): |                                  |
| ...                              |                                  |
| print(name, "cannot be deleted") |                                  |
| ...                              |                                  |
| >>> p = Permanent()              |                                  |
| >>> p.x = 9                      |                                  |
| >>> del p.x                      |                                  |
| x cannot be deleted              |                                  |
| >>> p.x                          |                                  |
| 9                                |                                  |
| ```                              |                                  |
+----------------------------------+----------------------------------+

#### Operator Overloading

Operator overloading allows us to use the built-in Python syntax and
operators to call functions which we define.

##### Binary Operators

+----------------------------------+---------------------------------:+
| If a class has the \_\_add\_\_   | +                                |
| function, we can use the \'+\'   | ------------------+------------+ |
| operator to add instances of the | |                                |
| class. This will call            |  Function         | Operator   | |
| \_\_add\_\_ with the two         | +                                |
| instances of the class passed as | ==================+============+ |
| parameters, and the return value | |                                |
| will be the result of the        |  \_\_add\_\_      | A + B      | |
| addition.                        | +                                |
|                                  | ------------------+------------+ |
| ``` python                       | |                                |
| >>> class FakeNumber:            |  \_\_sub\_\_      | A - B      | |
| ...     n = 5                    | +                                |
| ...     def __add__(A,B):        | ------------------+------------+ |
| ...         return A.n + B.n     | |                                |
| ...                              |  \_\_mul\_\_      | A \* B     | |
| >>> c = FakeNumber()             | +                                |
| >>> d = FakeNumber()             | ------------------+------------+ |
| >>> d.n = 7                      | |                                |
| >>> c + d                        |  \_\_truediv\_\_  | A / B      | |
| 12                               | +                                |
| ```                              | ------------------+------------+ |
|                                  | |                                |
| To override the augmented       |  \_\_floordiv\_\_ | A // B     | |
| assignmen                        | +                                |
| t | |                                |
| operators, merely add \'i\' in   |  \_\_mod\_\_      | A % B      | |
| front of the normal binary       | +                                |
| operator, i.e. for \'+=\' use    | ------------------+------------+ |
| \'\_\_iadd\_\_\' instead of      | |                                |
| \'\_\_add\_\_\'. The function    |  \_\_pow\_\_      | A \*\* B   | |
| will be given one argument,      | +                                |
| which will be the object on the  | ------------------+------------+ |
| right side of the augmented      | |                                |
| assignment operator. The         |  \_\_and\_\_      | A & B      | |
| returned value of the function   | +                                |
| will then be assigned to the     | ------------------+------------+ |
| object on the left of the        | |                                |
| operator.                        |  \_\_or\_\_       | A \| B     | |
|                                  | +                                |
| ``` python                       | ------------------+------------+ |
| >>                               | |                                |
| > c.__imul__ = lambda B: B.n - 6 |  \_\_xor\_\_      | A \^ B     | |
| >>> c *= d                       | +                                |
| >>> c                            | ------------------+------------+ |
| 1                                | |                                |
| ```                              |  \_\_eq\_\_       | A == B     | |
|                                  | +                                |
| It is important to note that the | ------------------+------------+ |
| augmented                       | |                                |
| assignmen                        |  \_\_ne\_\_       | A != B     | |
| t | ------------------+------------+ |
| operators will also use the      | |                                |
| normal operator functions if the |  \_\_gt\_\_       | A \> B     | |
| augmented operator function      | +                                |
| hasn\'t been set directly. This  | ------------------+------------+ |
| will work as expected, with      | |                                |
| \"\_\_add\_\_\" being called for |  \_\_lt\_\_       | A \< B     | |
| \"+=\" and so on.                | +                                |
|                                  | ------------------+------------+ |
| ``` python                       | |                                |
| >>> c = FakeNumber()             |  \_\_ge\_\_       | A \>= B    | |
| >>> c += d                       | +                                |
| >>> c                            | ------------------+------------+ |
| 12                               | |                                |
| ```                              |  \_\_le\_\_       | A \<= B    | |
|                                  | +                                |
|                                  | ------------------+------------+ |
|                                  | |                                |
|                                  |  \_\_lshift\_\_   | A \<\< B   | |
|                                  | +                                |
|                                  | ------------------+------------+ |
|                                  | |                                |
|                                  |  \_\_rshift\_\_   | A \>\> B   | |
|                                  | +                                |
|                                  | ------------------+------------+ |
|                                  | |                                |
|                                  |  \_\_contains\_\_ | A in B\    | |
|                                  | |                                |
|                                  |                   | A not in B | |
|                                  | +                                |
|                                  | ------------------+------------+ |
|                                  |                                  |
|                                  | : Binary Operator Override       |
|                                  | Functions                        |
+----------------------------------+----------------------------------+

##### Unary Operators

+----------------------------------+---------------------------------:+
| Unary operators will be passed   |   Function      Operator         |
| simply the instance of the class |   ------------- ----------       |
| that they are called on.         |   \_\_pos\_\_   +A               |
|                                  |   \_\_neg\_\_   -A               |
| ``` python                       |   \_\_inv\_\_   \~A              |
| >>> FakeNum                      |   \_\_abs\_\_   abs(A)           |
| ber.__neg__ = lambda A : A.n + 6 |   \_\_len\_\_   len(A)           |
| >>> -d                           |                                  |
| 13                               |   : Unary Operator Override      |
| ```                              |   Functions                      |
+----------------------------------+----------------------------------+

##### Item Operators

+----------------------------------+---------------------------------:+
| It is also possible in Python to |   Function           Operator    |
| override the indexing and       |   -                              |
| slic                             | ----------------- -------------- |
| ing |   \_\_setitem\_\_    C\[i\] = v  |
| operators. This allows us to use |   \_\_delitem\_\_    del C\[i\]  |
| the class\[i\] and class\[a:b\]  |   \_\_getslice\_\_   C\[s:e\]    |
| syntax on our own objects.       |                                  |
|                                  |  \_\_setslice\_\_   C\[s:e\] = v |
| The simplest form of item        |                                  |
| operator is \_\_getitem\_\_.     |  \_\_delslice\_\_   del C\[s:e\] |
| This takes as a parameter the    |                                  |
| instance of the class, then the  |   : Item Operator Override       |
| value of the index.              |   Functions                      |
|                                  |                                  |
| ``` python                       |                                  |
| >>> class FakeList:              |                                  |
| ...                              |                                  |
|     def __getitem__(self,index): |                                  |
| ...         return index * 2     |                                  |
| ...                              |                                  |
| >>> f = FakeList()               |                                  |
| >>> f['a']                       |                                  |
| 'aa'                             |                                  |
| ```                              |                                  |
|                                  |                                  |
| We can also define a function    |                                  |
| for the syntax associated with   |                                  |
| assigning a value to an item.    |                                  |
| The parameters for this function |                                  |
| include the value being          |                                  |
| assigned, in addition to the     |                                  |
| parameters from \_\_getitem\_\_  |                                  |
|                                  |                                  |
| ``` python                       |                                  |
| >>> class FakeList:              |                                  |
| ...     de                       |                                  |
| f __setitem__(self,index,value): |                                  |
| ...         self.str             |                                  |
| ing = index + " is now " + value |                                  |
| ...                              |                                  |
| >>> f = FakeList()               |                                  |
| >>> f['a'] = 'gone'              |                                  |
| >>> f.string                     |                                  |
| 'a is now gone'                  |                                  |
| ```                              |                                  |
|                                  |                                  |
| We can do the same thing with    |                                  |
| slices. Once again, each syntax  |                                  |
| has a different parameter list   |                                  |
| associated with it.              |                                  |
|                                  |                                  |
| ``` python                       |                                  |
| >>> class FakeList:              |                                  |
| ...     de                       |                                  |
| f __getslice___(self,start,end): |                                  |
| ...         retur                |                                  |
| n str(start) + " to " + str(end) |                                  |
| ...                              |                                  |
| >>> f = FakeList()               |                                  |
| >>> f[1:4]                       |                                  |
| '1 to 4'                         |                                  |
| ```                              |                                  |
|                                  |                                  |
| Keep in mind that one or both of |                                  |
| the start and end parameters can |                                  |
| be blank in slice syntax. Here,  |                                  |
| Python has default value for     |                                  |
| both the start and the end, as   |                                  |
| show below.                      |                                  |
|                                  |                                  |
| ``` python                       |                                  |
| >> f[:]                          |                                  |
| '0 to 2147483647'                |                                  |
| ```                              |                                  |
|                                  |                                  |
| Note that the default value for  |                                  |
| the end of the slice shown here  |                                  |
| is simply the largest possible   |                                  |
| signed integer on a 32-bit       |                                  |
| system, and may vary depending   |                                  |
| on your system and C compiler.   |                                  |
|                                  |                                  |
| -   \_\_setslice\_\_ has the     |                                  |
|     parameters                   |                                  |
|     (self,start,end,value)       |                                  |
|                                  |                                  |
| We also have operators for       |                                  |
| deleting items and slices.       |                                  |
|                                  |                                  |
| -   \_\_delitem\_\_ has the      |                                  |
|     parameters (self,index)      |                                  |
| -   \_\_delslice\_\_ has the     |                                  |
|     parameters (self,start,end)  |                                  |
|                                  |                                  |
| Note that these are the same as  |                                  |
| \_\_getitem\_\_ and              |                                  |
| \_\_getslice\_\_.                |                                  |
+----------------------------------+----------------------------------+

#### Other Overrides

+---+-----------------------------------------------:+
|   |   Function           Operator                  |
|   |   ------------------ ------------------------- |
|   |   \_\_cmp\_\_        cmp(x, y)                 |
|   |   \_\_hash\_\_       hash(x)                   |
|   |   \_\_nonzero\_\_    bool(x)                   |
|   |   \_\_call\_\_       f(x)                      |
|   |   \_\_iter\_\_       iter(x)                   |
|   |   \_\_reversed\_\_   reversed(x) (2.6+)        |
|   |   \_\_divmod\_\_     divmod(x, y)              |
|   |   \_\_int\_\_        int(x)                    |
|   |   \_\_long\_\_       long(x)                   |
|   |   \_\_float\_\_      float(x)                  |
|   |   \_\_complex\_\_    complex(x)                |
|   |   \_\_hex\_\_        hex(x)                    |
|   |   \_\_oct\_\_        oct(x)                    |
|   |   \_\_index\_\_                                |
|   |   \_\_copy\_\_       copy.copy(x)              |
|   |   \_\_deepcopy\_\_   copy.deepcopy(x)          |
|   |   \_\_sizeof\_\_     sys.getsizeof(x) (2.6+)   |
|   |   \_\_trunc\_\_      math.trunc(x) (2.6+)      |
|   |   \_\_format\_\_     format(x, \...) (2.6+)    |
|   |                                                |
|   |   : Other Override Functions                   |
+---+------------------------------------------------+

### Programming Practices

The flexibility of python classes means that classes can adopt a varied
set of behaviors. For the sake of understandability, however, it\'s best
to use many of Python\'s tools sparingly. Try to declare all methods in
the class definition, and always use the
`<class>`{=html}.`<member>`{=html} syntax instead of \_\_dict\_\_
whenever possible. Look at classes in
C++ and
Java#Java "wikilink") to see what most
programmers will expect from a class.

#### Encapsulation

Since all python members of a python class are accessible by
functions/methods outside the class, there is no way to enforce
encapsulation short of overriding
\_\_getattr\_\_, \_\_setattr\_\_ and \_\_delattr\_\_. General practice,
however, is for the creator of a class or module to simply trust that
users will use only the intended interface and avoid limiting access to
the workings of the module for the sake of users who do need to access
it. When using parts of a class or module other than the intended
interface, keep in mind that the those parts may change in later
versions of the module, and you may even cause errors or undefined
behaviors in the module.since encapsulation is private.

#### Doc Strings

When defining a class, it is convention to document the class using a
string literal at the start of the class definition. This string will
then be placed in the \_\_doc\_\_ attribute of the class definition.

``` python
>>> class Documented:
...     """This is a docstring"""
...     def explode(self):
...         """
...         This method is documented, too! The coder is really serious about
...         making this class usable by others who don't know the code as well
...         as he does.
...
...         """
...         print("boom")
>>> d = Documented()
>>> d.__doc__
'This is a docstring'
```

Docstrings are a very useful way to document your code. Even if you
never write a single piece of separate documentation (and let\'s admit
it, doing so is the lowest priority for many coders), including
informative docstrings in your classes will go a long way toward making
them usable.

Several tools exist for turning the docstrings in Python code into
readable API documentation, *e.g.*,
EpyDoc.

Don\'t just stop at documenting the class definition, either. Each
method in the class should have its own docstring as well. Note that the
docstring for the method *explode* in the example class *Documented*
above has a fairly lengthy docstring that spans several lines. Its
formatting is in accordance with the style suggestions of Python\'s
creator, Guido van Rossum in PEP
8.

#### Adding methods at runtime

##### To a class

It is fairly easy to add methods to a class at runtime. Lets assume that
we have a class called *Spam* and a function cook. We want to be able to
use the function cook on all instances of the class Spam:

``` python
class Spam:
  def __init__(self):
    self.myeggs = 5

def cook(self):
  print("cooking %s eggs" % self.myeggs)

Spam.cook = cook   #add the function to the class Spam
eggs = Spam()      #NOW create a new instance of Spam
eggs.cook()        #and we are ready to cook!
```

This will output

`cooking 5 eggs`

##### To an instance of a class

It is a bit more tricky to add methods to an instance of a class that
has already been created. Lets assume again that we have a class called
*Spam* and we have already created eggs. But then we notice that we
wanted to cook those eggs, but we do not want to create a new instance
but rather use the already created one:

``` python
class Spam:
  def __init__(self):
    self.myeggs = 5

eggs = Spam()

def cook(self):
  print("cooking %s eggs" % self.myeggs)

import types
f = types.MethodType(cook, eggs, Spam)
eggs.cook = f

eggs.cook()
```

Now we can cook our eggs and the last statement will output:

`cooking 5 eggs`

##### Using a function

We can also write a function that will make the process of adding
methods to an instance of a class easier.

``` python
def attach_method(fxn, instance, myclass):
  f = types.MethodType(fxn, instance, myclass)
  setattr(instance, fxn.__name__, f)
```

All we now need to do is call the attach_method with the arguments of
the function we want to attach, the instance we want to attach it to and
the class the instance is derived from. Thus our function call might
look like this:

``` python
attach_method(cook, eggs, Spam)
```

Note that in the function add_method we cannot write `instance.fxn = f`
since this would add a function called fxn to the instance.

### External links

-   9. Classes,
    docs.python.org
-   2. Built-in Functions \#
    vars,
    docs.python.org

fr:Programmation Python/Programmation orienté
objet
pt:Python/Conceitos
básicos/Classes


# Python Programming/Exceptions

Python 2 handles all errors with exceptions.

An *exception* is a signal that an error or other unusual condition has
occurred. There are a number of built-in exceptions, which indicate
conditions like reading past the end of a file, or dividing by zero. You
can also define your own exceptions.

### Overview

Exceptions in Python at a glance:

``` Python
import random
try:
  ri = random.randint(0, 2)
  if ri == 0:
    infinity = 1/0
  elif ri == 1:
    raise ValueError("Message")
    #raise ValueError, "Message" # Deprecated
  elif ri == 2:
    raise ValueError # Without message
except ZeroDivisionError:
  pass
except ValueError as valerr:
# except ValueError, valerr: # Deprecated?
  print(valerr)
  raise # Raises the exception just caught
except: # Any other exception
  pass
finally: # Optional
  pass # Clean up

class CustomValueError(ValueError): pass # Custom exception
try:
  raise CustomValueError
  raise TypeError
except (ValueError, TypeError): # Value error catches custom, a derived class, as well
  pass                          # A tuple catches multiple exception classes
```

### Raising exceptions

Whenever your program attempts to do something erroneous or meaningless,
Python raises exception to such conduct:

``` python
>>> 1 / 0
Traceback (most recent call last):
    File "<stdin>", line 1, in ?
ZeroDivisionError: integer division or modulo by zero
```

This *traceback* indicates that the `ZeroDivisionError` exception is
being raised. This is a built-in exception \-- see below for a list of
all the other ones.

### Catching exceptions

In order to handle errors, you can set up *exception handling blocks* in
your code. The keywords `try` and `except` are used to catch exceptions.
When an error occurs within the `try` block, Python looks for a matching
`except` block to handle it. If there is one, execution jumps there.

If you execute this code:

``` python
try:
    print(1/0)
except ZeroDivisionError:
    print("You can't divide by zero!")
```

Then Python will print this:

You can\'t divide by zero!

If you don\'t specify an exception type on the `except` line, it will
cheerfully catch all exceptions. This is generally a bad idea in
production code, since it means your program will blissfully ignore
*unexpected* errors as well as ones which the `except` block is actually
prepared to handle.

Exceptions can propagate up the call stack:

``` python
def f(x):
    return g(x) + 1

def g(x):
    if x < 0: raise ValueError, "I can't cope with a negative number here."
    else: return 5

try:
    print(f(-6))
except ValueError:
    print("That value was invalid.")
```

In this code, the `print` statement calls the function `f`. That
function calls the function `g`, which will raise an exception of type
ValueError. Neither `f` nor `g` has a `try`/`except` block to handle
ValueError. So the exception raised propagates out to the main code,
where there *is* an exception-handling block waiting for it. This code
prints:

That value was invalid.

Sometimes it is useful to find out exactly what went wrong, or to print
the python error text yourself. For example:

``` python
try:
    the_file = open("the_parrot")
except IOError, (ErrorNumber, ErrorMessage):
    if ErrorNumber == 2: # file not found
        print("Sorry, 'the_parrot' has apparently joined the choir invisible.")
    else:
        print("Congratulation! you have managed to trip a #%d error" % ErrorNumber)
        print(ErrorMessage)
```

Which will print:

Sorry, \'the_parrot\' has apparently joined the choir invisible.

#### Custom Exceptions

Code similar to that seen above can be used to create custom exceptions
and pass information along with them. This can be very useful when
trying to debug complicated projects. Here is how that code would look;
first creating the custom exception class:

``` python
class CustomException(Exception):
    def __init__(self, value):
        self.parameter = value
    def __str__(self):
        return repr(self.parameter)
```

And then using that exception:

``` python
try:
    raise CustomException("My Useful Error Message")
except CustomException, (instance):
    print("Caught: " + instance.parameter)
```

#### Trying over and over again

### Recovering and continuing with `finally`

Exceptions could lead to a situation where, after raising an exception,
the code block where the exception occurred might not be revisited. In
some cases this might leave external resources used by the program in an
unknown state.

`finally` clause allows programmers to close such resources in case of
an exception. Between 2.4 and 2.5 version of python there is change of
syntax for `finally` clause.

-   Python 2.4

``` python
try:
    result = None
    try:
        result = x/y
    except ZeroDivisionError:
        print("division by zero!")
    print("result is ", result)
finally:
    print("executing finally clause")
```

-   Python 2.5

``` python
try:
    result = x / y
except ZeroDivisionError:
    print("division by zero!")
else:
    print("result is", result)
finally:
    print("executing finally clause")
```

### Built-in exception classes

All built-in Python
exceptions

### Exotic uses of exceptions

Exceptions are good for more than just error handling. If you have a
complicated piece of code to choose which of several courses of action
to take, it can be useful to use exceptions to jump out of the code as
soon as the decision can be made. The Python-based mailing list software
Mailman does this in deciding how a message should be handled. Using
exceptions like this may seem like it\'s a sort of GOTO \-- and indeed
it is, but a limited one called an *escape continuation*. Continuations
are a powerful functional-programming tool and it can be useful to learn
them.

Just as a simple example of how exceptions make programming easier, say
you want to add items to a list but you don\'t want to use \"if\"
statements to initialize the list we could replace this:

``` python
if hasattr(self, 'items'):
    self.items.extend(new_items)
else:
    self.items = list(new_items)
```

Using exceptions, we can emphasize the normal program flow---that
usually we just extend the list---rather than emphasizing the unusual
case:

``` python
try:
    self.items.extend(new_items)
except AttributeError:
    self.items = list(new_items)
```

### External links

-   8. Errors and
    Exceptions in The
    Python Tutorial, docs.python.org
-   8. Errors and
    Exceptions in The
    Python Tutorial for Python 2.4, docs.python.org
-   6. Built-in
    Exceptions,
    docs.python.org


# Python Programming/Errors

In python there are three types of errors; *syntax
errors*, *logic
errors* and
*exceptions*.

## Syntax errors

Syntax errors are the most basic type of error. They arise when the
Python parser is unable to understand a line of code. Syntax errors are
almost always fatal, i.e. there is almost never a way to successfully
execute a piece of code containing syntax errors. Some syntax errors can
be caught and handled, like eval(\"\"), but these are rare.

In IDLE, it will highlight where the syntax error is. Most syntax errors
are typos, incorrect indentation, or incorrect arguments. If you get
this error, try looking at your code for any of these.

## Logic errors

These are the most difficult type of error to find, because they will
give unpredictable results and may crash your program.  A lot of
different things can happen if you have a logic error. However these are
very easy to fix as you can use a debugger, which will run through the
program and fix any problems.

A simple example of a logic error can be showcased below, the while loop
will compile and run however, the loop will never finish and may crash
Python:

``` python

#Counting Sheep
#Goal: Print number of sheep up until 101.
sheep_count=1
while sheep_count<100:
    print("%i Sheep"%sheep_count)
```

Logic errors are only erroneous in the perspective of the programming
goal one might have; in many cases Python is working as it was intended,
just not as the user intended. The above while loop is functioning
correctly as Python is intended to, but the exit the condition the user
needs is missing.

## Exceptions

Exceptions arise when the python parser knows what to do with a piece of
code but is unable to perform the action. An example would be trying to
access the internet with python without an internet connection; the
python interpreter knows what to do with that command but is unable to
perform it.

### Dealing with exceptions

Unlike syntax errors, exceptions are not always fatal. Exceptions can be
handled with the use of a `try` statement.

Consider the following code to display the HTML of the website
\'example.com\'. When the execution of the program reaches the try
statement it will attempt to perform the indented code following, if for
some reason there is an error (the computer is not connected to the
internet or something) the python interpreter will jump to the indented
code below the \'except:\' command.

``` python
import urllib2
url = 'http://www.example.com'
try:
    req = urllib2.Request(url)
    response = urllib2.urlopen(req)
    the_page = response.read()
    print(the_page)
except:
    print("We have a problem.")
```

Another way to handle an error is to except a specific error.

``` python
try:
    age = int(raw_input("Enter your age: "))
    print("You must be {0} years old.".format(age))
except ValueError:
    print("Your age must be numeric.")
```

If the user enters a numeric value as his/her age, the output should
look like this:

    Enter your age: 5
    Your age must be 5 years old.

However, if the user enters a non-numeric value as his/her age, a
`ValueError` is thrown when trying to execute the `int()` method on a
non-numeric string, and the code under the `except` clause is executed:

    Enter your age: five
    Your age must be numeric.

You can also use a `try` block with a `while` loop to validate input:

``` python
valid = False
while valid == False:
    try:
        age = int(raw_input("Enter your age: "))
        valid = True     # This statement will only execute if the above statement executes without error.
        print("You must be {0} years old.".format(age))
    except ValueError:
        print("Your age must be numeric.")
```

The program will prompt you for your age until you enter a valid age:

    Enter your age: five
    Your age must be numeric.
    Enter your age: abc10
    Your age must be numeric.
    Enter your age: 15
    You must be 15 years old.

In certain other cases, it might be necessary to get more information
about the exception and deal with it appropriately. In such situations
the except as construct can be used.

``` python
f=raw_input("enter the name of the file:")
l=raw_input("enter the name of the link:")
try:
    os.symlink(f,l)
except OSError as e:
    print("an error occurred linking %s to %s: %s\n error no %d"%(f,l,e.args[1],e.args[0]))
```

    enter the name of the file:file1.txt
    enter the name of the link:AlreadyExists.txt
    an error occurred linking file1.txt to AlreadyExists.txt: File exists
     error no 17

    enter the name of the file:file1.txt
    enter the name of the link:/Cant/Write/Here/file1.txt
    an error occurred linking file1.txt to /Cant/Write/Here/file1.txt: Permission denied
     error no 13

pt:Python/Conceitos básicos/Erros e
exceções


# Python Programming/Source Documentation and Comments

Documentation is the process of leaving information about your code. The
two mechanisms for doing this in Python are comments and documentation
strings.

## Comments

There will always be a time in which you have to return to your code.
Perhaps it is to fix a bug, or to add a new feature. Regardless, looking
at your own code after six months is almost as bad as looking at someone
else\'s code. What one needs is a means to leave reminders to yourself
as to what you were doing.

For this purpose, you leave comments. Comments are little snippets of
text embedded inside your code that are ignored by the Python
interpreter. A comment is denoted by the hash character (#) and extends
to the end of the line. For example:

``` python
#!/usr/bin/env python
# commentexample.py

# Display the knights that come after Scene 24
print("The Knights Who Say Ni!")
# print("I will never see the light of day!")
```

As you can see, you can also use comments to temporarily remove segments
of your code, like the second print statement.

### Comment Guidelines

The following guidelines are from PEP
8, written by Guido van
Rossum.

-   General
    -   Comments that contradict the code are worse than no comments.
        Always make a priority of keeping the comments up-to-date when
        the code changes!
    -   Comments should be complete sentences. If a comment is a phrase
        or sentence, its first word should be capitalized, unless it is
        an identifier that begins with a lower case letter (never alter
        the case of identifiers!).
    -   If a comment is short, the period at the end can be omitted.
        Block comments generally consist of one or more paragraphs built
        out of complete sentences, and each sentence should end in a
        period.
    -   You should use two spaces after a sentence-ending period.
    -   When writing English, Strunk and
        White applies.
    -   Python coders from non-English speaking countries: please write
        your comments in English, unless you are 120% sure that the code
        will never be read by people who don\'t speak your language.
-   Inline Comments
    -   An inline comment is a comment on the same line as a statement.
        Inline comments should be separated by at least two spaces from
        the statement. They should start with a \# and a single space.
    -   Inline comments are unnecessary and in fact distracting if they
        state the obvious. Don\'t do this:
        ``` python
        x = x + 1  # Increment x
        ```

        But sometimes, this is useful:

        ``` python
        x = x + 1  # Compensate for border
        ```

## Documentation Strings

But what if you just want to know how to use a function, class, or
method? You could add comments before the function, but comments are
inside the code, so you would have to pull up a text editor and view
them that way. But you can\'t pull up comments from a C extension, so
that is less than ideal. You could always write a separate text file
with how to call the functions, but that would mean that you would have
to remember to update that file. If only there was a mechanism for being
able to embed the documentation and get at it easily\...

Fortunately, Python has such a capability. Documentation strings (or
docstrings) are used to create easily-accessible documentation. You can
add a docstring to a function, class, or module by adding a string as
the first indented statement. For example:

``` python
#!/usr/bin/env python
# docstringexample.py

"""Example of using documentation strings."""

class Knight:
    """
    An example class.

    Call spam to get bacon.
    """

    def spam(eggs="bacon"):
        """Prints the argument given."""
        print(eggs)
```

The convention is to use triple-quoted strings, because it makes it
easier to add more documentation spanning multiple lines.

To access the documentation, you can use the `help` function inside a
Python shell with the object you want help on, or you can use the
`pydoc` command from your system\'s shell. If we were in the directory
where docstringexample.py lives, one could enter
`pydoc docstringexample` to get documentation on that module.


# Python Programming/Idioms

Python is a strongly idiomatic language: there is generally a single
optimal way of doing something (a
programming idiom), rather than many ways:
"There's more than one way to do
it" is *not* a Python
motto.

This section starts with some general principles, then goes through the
language, highlighting how to idiomatically use operations, data types,
and modules in the standard library.

## Principles

Use exceptions for
error-checking, following EAFP (It\'s Easier to Ask Forgiveness than
Permission) instead of LBYL (Look Before You Leap): put an action that
may fail inside a `try...except` block.

Use context managers
for managing resources, like files. Use `finally` for ad hoc cleanup,
but prefer to write a context manager to encapsulate this.

Use properties, not getter/setter pairs.

Use dictionaries for dynamic records, classes for static records (for
simple classes, use
collections.namedtuple):
if a record always has the same fields, make this explicit in a class;
if the fields may vary (be present or not), use a dictionary.

Use `_` for throwaway variables, like discarding a return value when a
tuple is returned, or to indicate that a parameter is being ignored
(when required for an interface, say). You can use `*_, **__` to discard
positional or keyword arguments passed to a function: these correspond
to the usual `*args, **kwargs` parameters, but explicitly discarded. You
can also use these in addition to positional or named parameters
(following the ones you use), allowing you to use some and discard any
excess ones.

Use implicit True/False (truthy/falsy values), except when needing to
distinguish between falsy values, like None, 0, and \[\], in which case
use an explicit check like `is None` or `== 0`.

Use the optional `else` clause after `try, for, while` not just `if`.

## Imports

For readable and robust code, only import modules, not names (like
functions or classes), as this creates a new (name) binding, which is
not necessarily in sync with the existing binding.[^1] For example,
given a module `m` which defines a function `f`, importing the function
with `from m import f` means that `m.f` and `f` can differ if either is
assigned to (creating a new binding).

In practice, this is frequently ignored, particularly for small-scale
code, as changing a module post-import is rare, so this is rarely a
problem, and both classes and functions are imported from modules so
they can be referred to without a prefix. However, for robust,
large-scale code, this is an important rule, as it risks creating very
subtle bugs.

For robust code with low typing, one can use a renaming import to
abbreviate a long module name:

``` python
import module_with_very_long_name as vl
vl.f()  # easier than module_with_very_long_name.f, but still robust
```

Note that importing submodules (or subpackages) from a
package
using `from` is completely fine:

``` python
from p import sm  # completely fine
sm.f()
```

## Operations

Swap values

``` python
b, a = a, b
```

Attribute access on nullable value

To access an attribute (esp. to call a method) on a value that might be
an object, or might be `None`, use the boolean shortcircuiting of `and`:

``` python
a and a.x
a and a.f()
```

Particularly useful for regex matches:

``` python
match and match.group(0)
```

in

`in` in can be used for substring checking

## Data types

### All sequence types

Indexing during iteration

Use `enumerate()` if you need to keep track of iteration cycles over an
iterable:

``` python
for i, x in enumerate(l):
    # ...
```

Anti-idiom:

``` python
for i in range(len(l)):
    x = l[i]  # why did you go from list to numbers back to the list?
    # ...
```

Finding first matching element

Python sequences do have an `index` method, but this returns the index
of the first occurrence of a specific value in the sequence. To find the
first occurrence of a value that satisfies a condition, instead, use
`next` and a generator expression:

``` python
try:
    x = next(i for i, n in enumerate(l) if n > 0)
except StopIteration:
    print('No positive numbers')
else:
    print('The index of the first positive number is', x)
```

If you need the value, not the index of its occurrence, you can get it
directly through:

``` python
try:
    x = next(n for n in l if n > 0)
except StopIteration:
    print('No positive numbers')
else:
    print('The first positive number is', x)
```

The reason for this construct is twofold:

-   Exceptions let you signal "no match found" (they solve the
    semipredicate problem): since you\'re returning a single value (not
    an index), this can\'t be returned in the value.
-   Generator expressions let you use an expression without needing a
    lambda or introducing new grammar.

Truncating

For mutable sequences, use `del`, instead of reassigning to a slice:

``` python
del l[j:]
del l[:i]
```

Anti-idiom:

``` python
l = l[:j]
l = l[i:]
```

The simplest reason is that `del` makes your intention clear: you\'re
truncating.

More subtly, slicing creates another reference to the same list (because
lists are mutable), and then unreachable data can be garbage-collected,
but generally this is done later. Deleting instead immediately modifies
the list in-place (which is faster than creating a slice and then
assigning it to the existing variable), and allows Python to immediately
deallocate the deleted elements, instead of waiting for garbage
collection.

In some cases you *do* want 2 slices of the same list -- though this is
rare in basic programming, other than iterating once over a slice in a
`for` loop -- but it\'s rare that you\'ll want to make a slice of a
whole list, then replace the original list variable with a slice (but
not change the other slice!), as in the following funny-looking code:

``` python
m = l
l = l[i:j]  # why not m = l[i:j] ?
```

Sorted list from an iterable

You can create a sorted list directly from any iterable, without needing
to first make a list and then sort it. These include sets and
dictionaries (iterate on the keys):

``` python
s = {1, 'a', ...}
l = sorted(s)
d = {'a': 1, ...}
l = sorted(d)
```

### Tuples

Use tuples for constant sequences. This is rarely necessary (primarily
when using as keys in a dictionary), but makes intention clear.

### Strings

Substring

Use `in` for substring checking.

However, do *not* use `in` to check if a string is a single-character
match, since it matches substrings and will return spurious matches --
instead use a tuple of valid values. For example, the following is
wrong:

``` python
def valid_sign(sign):
    return sign in '+-'  # wrong, returns true for sign == '+-'
```

Instead, use a tuple:

``` python
def valid_sign(sign):
    return sign in ('+', '-')
```

Building a string

To make a long string incrementally, build a list and then join it with
`''` -- or with newlines, if building a text file (don\'t forget the
final newline in this case!). This is faster and clearer than appending
to a string, which is often *slow.* (In principle can be $O(nk)$ in
overall length of string and number of additions, which is $O(n^2)$ if
pieces are of similar sizes.)

However, there are some optimizations in some versions CPython that make
simple string appending fast -- string appending in CPython 2.5+, and
bytestring appending in CPython 3.0+ are fast, but for building Unicode
strings (unicode in Python 2, string in Python 3), joining is faster. If
doing extensive string manipulation, be aware of this and profile your
code. See Performance Tips: String
Concatenation
and Concatenation Test
Code for details.

Don\'t do this:

``` python
s = ''
for x in l:
    # this makes a new string every iteration, because strings are immutable
    s += x
```

Instead:

``` python
# ...
# l.append(x)
s = ''.join(l)
```

You can even use generator expressions, which are extremely efficient:

``` python
s = ''.join(f(x) for x in l)
```

If you do want a mutable string-like object, you can use `StringIO`.

-   Efficient String Concatenation in
    Python -- old article
    (so benchmarks out of date), but gives overview of some techniques.

### Dictionaries

To iterate through a dictionary, either keys, values, or both:

``` python
# Iterate over keys
for k in d:
    ...

# Iterate over values, Python 3
for v in d.values():
    ...

# Iterate over values, Python 2
# In Python 2, dict.values() returns a copy
for v in d.itervalues():
    ...

# Iterate over keys and values, Python 3
for k, v in d.items():
    ...

# Iterate over values, Python 2
# In Python 2, dict.items() returns a copy
for k, v in d.iteritems():
    ...
```

Anti-patterns:

``` python
for k, _ in d.items():  # instead: for k in d:
    ...
for _, v in d.items():  # instead: for v in d.values()
    ...
```

FIXME:

-   setdefault
-   usually better to use collections.defaultdict

`dict.get` is useful, but using `dict.get` and then checking if it is
`None` as a way of testing if the key is in the dictionary is an
anti-idiom, as `None` is a potential value, and whether the key is in
the dictionary can be checked directly. It\'s ok to use `get` and
compare with `None` if this is _not_ a potential
value, however.

Simple:

``` python
if 'k' in d:
    # ... d['k']
```

Anti-idiom (unless `None` is not a potential value):

``` python
v = d.get('k')
if v is not None:
    # ... v
```

Dict from parallel sequences of keys and values

Use `zip` as: `dict(zip(keys, values))`

## Modules

### re

Match if found, else `None`:

``` python
match = re.match(r, s)
return match and match.group(0)
```

\...returns `None` if no match, and the match contents if there is one.

## References

-   "Idioms and Anti-Idioms in
    Python", Moshe
    Zadka

## Further reading

-   "PEP 20 \-- The Zen of
    Python", Tim Peters

[^1]: "Idioms and Anti-Idioms in
    Python": from
    module import name1,
    name2


# Python Programming/Package management

*pip* is the standard Python package manager, making it easy to download
and install packages from the PyPI repository. pip seems to be part of
Python distribution since Python 2.7.9 and 3.5.4. If you do not have
pip, you can install it by downloading get-pip.py from bootstrap.pypa.io
and running python get-pip.py. Other package managers are not covered in
this chapter.

Examples of pip use:

-   pip install xlrd
    -   Installs xlrd package from the PyPI repository, or from another
        repository if customized to search in additional repositories.
-   pip install \--upgrade xlrd
    -   Upgrades a package to the latest version.
-   pip install mypackage.whl
    -   Installs the package from wheel file mypackage.whl. This is
        useful when for whatever reason installation from PyPI fails and
        you need to download the wheel file (.whl) of the package
        manually.
-   pip freeze
    -   Lists installed packages and their versions.
-   pip show xlrd
    -   Outputs information about an installed package (here xlrd),
        including version, author and license.
-   python -m pip install xlrd
    -   Calls pip via python and -m option. Useful e.g. for installing
        packages for ../PyPy/ (a just-in-time
        compiler for Python), in which case you use pypy -m pip install
        xlrd.
-   pip \--version
    -   Outputs the pip version.
-   pip install \--upgrade pip
    -   Upgrades pip itself.

*PyPI* is an online repository of Python packages, many of which are
published under a rather permissive license such as MIT license or one
of the BSD licenses. PyPI hosts both pure-Python packages and Python
packages taking advantage of the C language. Installing pure-Python
packages such as xlrd is usually seamless. As for C language packages,
many of them have precompiled binaries for multiple operating systems,
making the installation seamless as well. However, for a C language
package that has only sources published, pip needs a working and
properly set up compiler to successfully install the package.

A *wheel file* is a package distribution. It can contain pure-Python
code but also precompiled executable binaries if required. A single
package can offer multiple wheels per different Python versions and
operating systems. An example wheel file containing precompiled binaries
is numpy-1.16.2-cp27-cp27m-win32.whl, for numpy package, available from
pypi Download files section for
the package. If you are using pip with no problems, you do not need to
worry about wheel files.

## requirements.txt

This file lists the application dependencies. It\'s equivalent to
composer.json in PHP or package.json in JavaScript.

File generation:

`pip freeze > requirements.txt`

Dependencies installation:

`pip install -r requirements.txt`

## External links

-   pip - The Python Package
    Installer, pip.pypa.io
-   Installation
    in pip documentation, pip.pypa.io
-   How do I install pip on
    Windows?,
    stackoverflow.com
-   Installing
    Packages,
    packaging.python.org
-   Packaging Python
    Projects,
    packaging.python.org
-   The Python Package Index (PyPI), pypi.org
-   Over 10% of Python Packages on PyPI are Distributed Without Any
    License,
    2018, snyk.io


# Python Programming/Python 2 vs. Python 3

Python 3 was created incompatible with Python 2. Support for Python 2.7
ended in 2020.

One noticeable difference is that in Python 3, *print* is not a
statement but rather a function, and therefore, invoking it requires
placing brackets around its arguments. Differences with deeper impact
include making all strings Unicode and introducing a bytes type, making
all integers big integers, letting slash (/) denote a true division
rather than per default integer division, etc.; for a compact overview,
see Python wiki.

Python 2 code can be made ready for a switch to Python 3 by importing
features from \_\_future\_\_ module. For instance, *from \_\_future\_\_
import print_function* makes Python 2 behave as if it had Python 3 print
function.

Python 3 was first released in 2008.

A list of Python packages ready for Python 3 is available from
py3readiness.org.

A survey conducted in 2018 by JetBrains and Python Software Foundation
suggests significant adoption of Python 3 among Python users.

## External links

-   W:History of Python#Version
    3, en.wikipedia.org
-   What's New In Python
    3.0, docs.python.org
-   28.11. \_\_future\_\_ --- Future statement
    definitions,
    docs.python.org
-   Porting Python 2 Code to Python
    3, docs.python.org
-   Cheat Sheet: Writing Python 2-3 compatible
    code,
    python-future.org
-   Should I use Python 2 or Python 3 for my development
    activity?,
    wiki.python.org
-   Python3.0, wiki.python.org
-   Python 3 Readiness, pyreadiness.org
-   PEP 373 \-- Python 2.7 Release
    Schedule,
    legacy.python.org
-   Python Developers Survey 2018
    Results,
    jetbrains.com (conducted with Python Software Foundation)
-   How we rolled out one of the largest Python 3 migrations
    ever,
    2018, blogs.dropbox.com


# Python Programming/Decorators

Duplicated code is recognized as bad practice in software for lots of
reasons, not least of which is that it requires more work to maintain.
If you have the same algorithm operating twice on different pieces of
data you can put the algorithm in a function and pass in the data to
avoid having to duplicate the code. However, sometimes you find cases
where the code itself changes, but two or more places still have
significant chunks of duplicated boilerplate code. A typical example
might be logging:

``` python
def multiply(a, b):
    result = a * b
    log("multiply has been called")
    return result

def add(a, b):
    result = a + b
    log("add has been called")
    return result
```

In a case like this, it\'s not obvious how to factor out the
duplication. We can follow our earlier pattern of moving the common code
to a function, but calling the function with different data is not
enough to produce the different behavior we want (add or multiply).
Instead, we have to pass a *function* to the common function. This
involves a function that operates on a function, known as a
*higher-order function*.

Decorator in Python is a syntax sugar for high-level function.

Minimal example of property decorator:

``` python
>>> class Foo(object):
...     @property
...     def bar(self):
...         return 'baz'
...
>>> F = Foo()
>>> print(F.bar)
baz
```

The above example is really just a syntax sugar for codes like this:

``` python
>>> class Foo(object):
...     def bar(self):
...         return 'baz'
...     bar = property(bar)
...
>>> F = Foo()
>>> print(F.bar)
baz
```

Minimal Example of generic decorator:

``` python
>>> def decorator(f):
...     def called(*args, **kargs):
...         print('A function is called somewhere')
...         return f(*args, **kargs)
...     return called
...
>>> class Foo(object):
...     @decorator
...     def bar(self):
...         return 'baz'
...
>>> F = Foo()
>>> print(F.bar())
A function is called somewhere
baz
```

A good use for the decorators is to allow you to refactor your code so
that common features can be moved into decorators. Consider for example,
that you would like to trace all calls to some functions and print out
the values of all the parameters of the functions for each invocation.
Now you can implement this in a decorator as follows:

``` python
#define the Trace class that will be
#invoked using decorators
class Trace(object):
    def __init__(self, f):
        self.f =f

    def __call__(self, *args, **kwargs):
        print("entering function " + self.f.__name__)
        i=0
        for arg in args:
            print("arg {0}: {1}".format(i, arg))
            i =i+1

        return self.f(*args, **kwargs)
```

Then you can use the decorator on any function that you defined by:

``` python

@Trace
def sum(a, b):
    print "inside sum"
    return a + b
```

On running this code you would see output like

``` python
>>> sum(3,2)
entering function sum
arg 0: 3
arg 1: 2
inside sum
```

Alternately, instead of creating the decorator as a class, you could
have used a function as well.

``` python
def Trace(f):
    def my_f(*args, **kwargs):
        print("entering " +  f.__name__)
        result= f(*args, **kwargs)
        print("exiting " +  f.__name__)
        return result
    my_f.__name = f.__name__
    my_f.__doc__ = f.__doc__
    return my_f

#An example of the trace decorator
@Trace
def sum(a, b):
    print("inside sum")
    return a + b

#if you run this you should see
>>> sum(3,2)
entering sum
inside sum
exiting sum
5
```

Remember it is good practice to return the function or a sensible
decorated replacement for the function so that decorators can be
chained.


# Python Programming/Context Managers

A basic issue in programming is resource
management "wikilink"): a
resource "wikilink") is anything in limited
supply, notably file handles, network sockets,
locks, etc., and a key problem is making sure these are *released* after
they are *acquired.* If they are not released, you have a
resource leak, and the system may slow down or
crash. More generally, you may want cleanup actions to always be done,
other than simply releasing resources.

Python provides special syntax for this in the `with`
statement,
which automatically manages resources encapsulated within context
manager
types,
or more generally performs startup and cleanup actions around a block of
code. You should **always** use a `with` statement for resource
management. There are many built-in context manager types, including the
basic example of `File`, and it is easy to write your own. The code is
not hard, but the concepts are slightly subtle, and it is easy to make
mistakes.

## Basic resource management

Basic resource management uses an explicit pair of `open()...close()`
functions, as in basic file opening and closing. ***Don\'t do this,***
for the reasons we are about to explain:

``` python
f = open(filename)
# ...
f.close()
```

The key problem with this simple code is that it fails if there is an
early return, either due to a `return` statement or an exception,
possibly raised by called code. To fix this, ensuring that the cleanup
code is called when the block is exited, one uses a `try...finally`
clause:

``` python
f = open(filename)
try:
    # ...
finally:
    f.close()
```

However, this still requires manually releasing the resource, which
might be forgotten, and the release code is distant from the acquisition
code. The release can be done automatically by instead using `with`,
which works because `File` is a context manager type:

``` python
with open(filename) as f:
    # ...
```

This assigns the value of `open(filename)` to `f` (this point is subtle
and varies between context managers), and then automatically releases
the resource, in this case calling `f.close()`, when the block exits.

## Technical details

Newer objects are *context managers* (formally context manager
types:
subtypes, as they implement the context manager interface, which
consists of `__enter__()`, `__exit__()`), and thus can be used in `with`
statements easily (see With Statement Context
Managers).

For older file-like objects that have a `close` method but not
`__exit__()`, you can use the
`@contextlib.closing`
decorator. If you need to roll your own, this is very easy, particularly
using the
`@contextlib.contextmanager`
decorator.[^1]

Context managers work by calling `__enter__()` when the `with` context
is entered, binding the return value to the target of `as`, and calling
`__exit__()` when the context is exited. There\'s some subtlety about
handling exceptions during exit, but you can ignore it for simple use.

More subtly, `__init__()` is called when an object is created, but
`__enter__()` is called when a `with` context is entered.

The `__init__()`/`__enter__()` distinction is important to distinguish
between single use, reusable and reentrant context
managers.
It\'s not a meaningful distinction for the common use case of
instantiating an object in the `with` clause, as follows:

``` python
with A() as a:
    ...
```

\...in which case any single use context manager is fine.

However, in general it is a difference, notably when distinguishing a
reusable context manager from the resource it is managing, as in here:

``` python
a_cm = A()
with a_cm as a:
   ...
```

Putting resource acquisition in `__enter__()` instead of `__init__()`
gives a reusable context
manager.

Notably, `File()` objects do the initialization in `__init__()` and then
just returns itself when entering a context, as in
`def __enter__(): return self`. This is fine if you want the target of
the `as` to be bound to an *object* (and allows you to use factories
like `open` as the source of the `with` clause), but if you want it to
be bound to something else, notably a *handle* (file name or file
handle/file descriptor), you want to wrap the actual object in a
separate context manager. For example:

``` python
@contextmanager
def FileName(*args, **kwargs):
   with File(*args, **kwargs) as f:
       yield f.name
```

For simple uses you don\'t need to do any `__init__()` code, and only
need to pair `__enter__()`/`__exit__()`. For more complicated uses you
can have reentrant context
managers,
but that\'s not necessary for simple use.

## Caveats

### `try...finally`

Note that a `try...finally` clause *is* necessary with
`@contextlib.contextmanager`, as this does not catch any exceptions
raised after the `yield`, but is *not* necessary in `__exit__()`, which
is called even if an exception is raised.

### Context, not scope

The term *context* manager is carefully chosen, particularly in contrast
to "scope". Local variables in Python have function scope, and thus the
target of a `with` statement, if any, is still visible after the block
has exited, though `__exit__()` has already been called on the context
manager (the argument of the `with` statement), and thus is often not
useful or valid. This is a technical point, but it\'s worth
distinguishing the `with` statement context from the overall function
scope.

### Generators

Generators that hold or use resources are a bit tricky.

Beware that creating generators within a `with` statement and then using
them outside the block does *not* work, because generators have deferred
evaluation, and thus when they are evaluated, the resource has already
been released. This is most easily seen using a file, as in this
generator expression to convert a file to a list of lines, stripping the
end-of-line character:

``` python
with open(filename) as f:
    lines = (line.rstrip('\n') for line in f)
```

When `lines` is then used -- evaluation can be forced with `list(lines)`
-- this fails with `<samp>`{=html}ValueError: I/O operation on closed
file.`</samp>`{=html} This is because the file is closed at the end of
the `with` statement, but the lines are not read until the generator is
evaluated.

The simplest solution is to avoid generators, and instead use lists,
such as list comprehensions. This is generally appropriate in this case
(reading a file) since one wishes to minimize system calls and just read
the file all at once (unless the file is very large):

``` python
with open(filename) as f:
    lines = [line.rstrip('\n') for line in f]
```

In case that one does wish to use a resource in a generator, the
resource must be held within the generator, as in this generator
function:

``` python
def stripped_lines(filename):
    with open(filename) as f:
        for line in f:
            yield line.rstrip('\n')
```

As the nesting makes clear, the file is kept open while iterating
through it.

To release the resource, the generator must be explicitly closed, using
`generator.close()``,`
just as with other objects that hold resources (this is the dispose
pattern). This can in turn be automated
by making the generator into a context manager, using
`@contextlib.closing,` as:

``` python
from contextlib import closing

with closing(stripped_lines(filename)) as lines:
    # ...
```

### Not RAII

is an alternative form of resource management, particularly used in C++.
In RAII, resources are acquired during object construction, and released
during object destruction. In Python the analogous functions are
`__init__()` and
`__del__()`
(finalizer), but RAII does *not* work in Python, and releasing resources
in `__del__()` does *not* work. This is because there is no guarantee
that `__del__()` will be called: it\'s just for memory manager use, not
for resource handling.

In more detail, Python object construction is two-phase, consisting of
(memory) allocation in `__new__()` and (attribute) initialization in
`__init__()`. Python is garbage-collected via reference counting, with
objects being finalized (not destructed) by `__del__()`. However,
finalization is non-deterministic (objects have non-deterministic
lifetimes), and the finalizer may be called much later or not at all,
particularly if the program crashes. Thus using `__del__()` for resource
management will generally leak resources.

It is possible to use finalizers for resource management, but the
resulting code is implementation-dependent (generally working in CPython
but not other implementations, such as PyPy) and fragile to version
changes. Even if this is done, it requires great care to ensure
references drop to zero in all circumstances, including: exceptions,
which contain references in tracebacks if caught or if running
interactively; and references in global variables, which last until
program termination. Prior to Python 3.4, finalizers on objects in
cycles were also a serious problem, but this is no longer a problem;
however, finalization of objects in cycles is not done in a
deterministic order.

## References

-   Context Manager
    Types
-   With Statement Context
    Managers

## External links

-   Get With the Program as
    Contextmanager
-   PyMOTW (Module of the Week):
    contextlib
-   Markus Gattol: Context
    Manager

[^1]: Nils von
    Barth's
    answer to "how to delete dir created by python
    tempfile.mkdtemp",
    *StackOverflow*


# Python Programming/Reflection

A Python script can find out about the type, class, attributes and
methods of an object. This is referred to as **reflection** or
**introspection**. See also
../Metaclasses/.

Reflection-enabling functions include type(), isinstance(), callable(),
dir() and getattr().

## Type

The type method enables to find out about the type of an object. The
following tests return True:

-   type(3) is int

-   type(3.0) is float

-   type(10\*\*10) is long \# Python 2

-   type(1 + 1j) is complex

-   type(\'Hello\') is str

-   type(\[1, 2\]) is list

-   type(\[1, \[2, \'Hello\'\]\]) is list

-   type({\'city\': \'Paris\'}) is dict

-   type((1,2)) is tuple

-   type(set()) is set

-   type(frozenset()) is frozenset

-

    ------------------------------------------------------------------------

-   type(3).\_\_name\_\_ == \"int\"

-   type(\'Hello\').\_\_name\_\_ == \"str\"

-

    ------------------------------------------------------------------------

-   import types, re, Tkinter \# For the following examples

-   type(re) is types.ModuleType

-   type(re.sub) is types.FunctionType

-   type(Tkinter.Frame) is types.ClassType

-   type(Tkinter.Frame).\_\_name\_\_ == \"classobj\"

-   type(Tkinter.Frame()).\_\_name\_\_ == \"instance\"

-   type(re.compile(\'myregex\')).\_\_name\_\_ == \"SRE_Pattern\"

-   type(type(3)) is types.TypeType

The type function disregards class inheritance: \"type(3) is object\"
yields False while \"isinstance(3, object)\" yields True.

Links:

-   2. Built-in Functions \#
    type,
    python.org
-   8.15. types --- Names for built-in
    types, python.org

## Isinstance

Determines whether an object is an instance of a type or class.

The following tests return True:

-   isinstance(3, int)
-   isinstance(\[1, 2\], list)
-   isinstance(3, object)
-   isinstance(\[1, 2\], object)
-   import Tkinter; isinstance(Tkinter.Frame(), Tkinter.Frame)
-   import Tkinter; Tkinter.Frame().\_\_class\_\_.\_\_name\_\_ ==
    \"Frame\"

Note that isinstance provides a weaker condition than a comparison using
#Type.

Function isinstance and a user-defined class:

``` python
class Plant: pass                        # Dummy class
class Tree(Plant): pass                  # Dummy class derived from Plant
tree = Tree()                            # A new instance of Tree class
print(isinstance(tree, Tree))            # True
print(isinstance(tree, Plant))           # True
print(isinstance(tree, object))          # True
print(type(tree) is Tree)                # True
print(type(tree).__name__ == "instance") # False
print(tree.__class__.__name__ == "Tree") # True
```

Links:

-   Built-in Functions \#
    isinstance,
    python.org
-   isinstance() considered
    harmful, canonical.org

## Issubclass

Determines whether a class is a subclass of another class. Pertains to
classes, not their instances.

``` python
class Plant: pass                        # Dummy class
class Tree(Plant): pass                  # Dummy class derived from Plant
tree = Tree()                            # A new instance of Tree class
print(issubclass(Tree, Plant))           # True
print(issubclass(Tree, object))          # False in Python 2
print(issubclass(int, object))           # True
print(issubclass(bool, int))             # True
print(issubclass(int, int))              # True
print(issubclass(tree, Plant))           # Error - tree is not a class
```

Links:

-   Built-in Functions \#
    issubclass,
    python.org

## Duck typing

Duck typing provides an indirect means of reflection. It is a technique
consisting in using an object as if it was of the requested type, while
catching exceptions resulting from the object not supporting some of the
features of the class or type.

Links:

-   Glossary \#
    duck-typing,
    python.org

## Callable

For an object, determines whether it can be called. A class can be made
callable by providing a \_\_call\_\_() method.

Examples:

-   callable(2)
    -   Returns False. Ditto for callable(\"Hello\") and callable(\[1,
        2\]).
-   callable(\[1,2\].pop)
    -   Returns True, as pop without \"()\" returns a function object.
-   callable(\[1,2\].pop())
    -   Returns False, as \[1,2\].pop() returns 2 rather than a function
        object.

Links:

-   Built-in Functions \#
    callable,
    python.org

## Dir

Returns the list of names of attributes of an object, which includes
methods. Is somewhat heuristic and possibly incomplete, as per
python.org.

Examples:

-   dir(3)
-   dir(\"Hello\")
-   dir(\[1, 2\])
-   import re; dir(re)
    -   Lists names of functions and other objects available in the re
        module for regular expressions.

Links:

-   Built-in Functions \#
    dir,
    python.org

## Getattr

Returns the value of an attribute of an object, given the attribute name
passed as a string.

An example:

-   getattr(3, \"imag\")

The list of attributes of an object can be obtained using
#Dir.

Links:

-   Built-in Functions \#
    getattr,
    python.org

## Keywords

A list of Python keywords can be obtained from Python:

``` python
import keyword
pykeywords = keyword.kwlist
print(keyword.iskeyword("if"))     # True
print(keyword.iskeyword("True"))   # False
```

Links:

-   32.6. keyword --- Testing for Python
    keywords,
    python.org

## Built-ins

A list of Python built-in objects and functions can be obtained from
Python:

``` python
print(dir(__builtins__))          # Output the list
print(type(__builtins__.list))    # = <type 'type'>
print(type(__builtins__.open))    # = <type 'builtin_function_or_method'>
print(list is __builtins__.list)  # True
print(open is __builtins__.open)  # True
```

Links:

-   28.3. \_\_builtin\_\_ --- Built-in
    objects,
    python.org
-   Built-in Functions \#
    dir,
    python.org

## External links

-   2. Built-in
    Functions,
    docs.python.org
-   How to determine the variable type in
    Python?,
    stackoverflow.com
-   Differences between isinstance() and type() in
    python,
    stackoverflow.com
-   W:Reflection
    (computer_programming)#Python#Python "wikilink"),
    Wikipedia
-   W:Type
    introspection#Python,
    Wikipedia


# Python Programming/Metaclasses

In Python, classes are themselves objects. Just as other objects are
instances of a particular class, classes themselves are instances of a
metaclass.

### Python3

The Pep 3115 defines the
changes to python 3 metaclasses. In python3 you have a method
\_\_prepare\_\_ that is called in the metaclass to create a dictionary
or other class to store the class members.[^1] Then there is the
\_\_new\_\_ method that is called to create new instances of that class.
[^2]

### The type Metaclass

The metaclass for all standard Python types is the \"type\" object.

``` python
>>> type(object)
<type 'type'>
>>> type(int)
<type 'type'>
>>> type(list)
<type 'type'>
```

Just like list, int and object, \"type\" is itself a normal Python
object, and is itself an instance of a class. In this case, it is in
fact an instance of itself.

``` python
>>> type(type)
<type 'type'>
```

It can be instantiated to create new class objects similarly to the
class factory example above by passing the name of the new class, the
base classes to inherit from, and a dictionary defining the namespace to
use.

For instance, the code:

``` python
>>> class MyClass(BaseClass):
...     attribute = 42
```

Could also be written as:

``` python
>>> MyClass = type("MyClass", (BaseClass,), {'attribute' : 42})
```

### Metaclasses

It is possible to create a class with a different metaclass than type by
setting the metaclass keyword argument when defining the class. When
this is done, the class, and its subclass will be created using your
custom metaclass. For example

``` python
class CustomMetaclass(type):
    def __init__(cls, name, bases, dct):
        print("Creating class %s using CustomMetaclass" % name)
        super(CustomMetaclass, cls).__init__(name, bases, dct)

class BaseClass(metaclass=CustomMetaclass):
    pass

class Subclass1(BaseClass):
    pass
```

This will print

`Creating class BaseClass using CustomMetaclass`\
`Creating class Subclass1 using CustomMetaclass`

By creating a custom metaclass in this way, it is possible to change how
the class is constructed. This allows you to add or remove attributes
and methods, register creation of classes and subclasses creation and
various other manipulations when the class is created.

### More resources

-   Wikipedia article on Aspect Oriented
    Programming
-   Unifying types and classes in Python
    2.2
-   O\'Reilly Article on Python
    Metaclasses

### References

[^1]: <http://www.python.org/dev/peps/pep-3115/>

[^2]: <http://eli.thegreenplace.net/2011/08/14/python-metaclasses-by-example/>