\pagenumbering{arabic}
+
\chapter{Whetting Your Appetite}
If you ever wrote a large shell script, you probably know this
reference material about built-in and standard types, functions and
modules that can save you a lot of time when writing Python programs.
+
\chapter{Using the Python Interpreter}
\section{Invoking the Interpreter}
command to check (or even suggest) matching parentheses, quotes etc.
would also be useful.
+
\chapter{An Informal Introduction to Python}
In the following examples, input and output are distinguished by the
\end{itemize}
+
\chapter{More Control Flow Tools}
Besides the {\tt while} statement just introduced, Python knows the
\end{itemize}
+
\chapter{Odds and Ends}
This chapter describes some things you've learned about already in
the language.
}
+
\chapter{Modules}
If you quit from the Python interpreter and enter it again, the
>>>
\end{verbatim}\ecode
+
\chapter{Output Formatting}
So far we've encountered two ways of writing values: {\em expression
>>>
\end{verbatim}\ecode
+
\chapter{Errors and Exceptions}
Until now error messages haven't been more than mentioned, but if you
It is also executed when the {\tt try} statement is left via a
{\tt break} or {\tt return} statement.
+
+\chapter{Classes}
+
+Python's class mechanism adds classes to the language with a minimum
+of new syntax and semantics. It is a mixture of the class mechanisms
+found in C++ and Modula-3. As is true for modules, classes in Python
+do not put an absolute barrier between definition and user, but rather
+rely on the politeness of the user not to ``break into the
+definition.'' The most important features of classes are retained
+with full power, however: the class inheritance mechanism allows
+multiple base classes, a derived class can override any methods of its
+base class(es), a method can call the method of a base class with the
+same name. Objects can contain an arbitrary amount of private data.
+
+In C++ terminology, all class members (including the data members) are
+{\em public}, and all member functions are {\em virtual}. There are
+no special constructors or desctructors. As in Modula-3, there are no
+shorthands for referencing the object's members from its methods: the
+method function is declared with an explicit first argument
+representing the object, which is provided implicitly by the call. As
+in Smalltalk, classes themselves are objects, albeit in the wider
+sense of the word: in Python, all data types are objects. This
+provides semantics for importing and renaming. But, just like in C++
+or Modula-3, built-in types cannot be used as base classes for
+extension by the user. Also, like in Modula-3 but unlike in C++, the
+built-in operators with special syntax (arithmetic operators,
+subscriptong etc.) cannot be redefined for class members.
+
+
+\section{A word about terminology}
+
+Lacking universally accepted terminology to talk about classes, I'll
+make occasional use of Smalltalk and C++ terms. (I'd use Modula-3
+terms, since its object-oriented semantics are closer to those of
+Python than C++, but I expect that few readers have heard of it...)
+
+I also have to warn you that there's a terminological pitfall for
+object-oriented readers: the word ``object'' in Python does not
+necessarily mean a class instance. Like C++ and Modula-3, and unlike
+Smalltalk, not all types in Python are classes: the basic built-in
+types like integers and lists aren't, and even somewhat more exotic
+types like files aren't. However, {\em all} Python types share a little
+bit of common semantics that is best described by using the word
+object.
+
+Objects have individuality, and multiple names (in multiple scopes)
+can be bound to the same object. This is known as aliasing in other
+languages. This is usually not appreciated on a first glance at
+Python, and can be safely ignored when dealing with immutable basic
+types (numbers, strings, tuples). However, aliasing has an
+(intended!) effect on the semantics of Python code involving mutable
+objects such as lists, dictionaries, and most types representing
+entities outside the program (files, windows, etc.). This is usually
+used to the benefit of the program, since aliases behave like pointers
+in some respects. For example, passing an object is cheap since only
+a pointer is passed by the implementation; and if a function modifies
+an object passed as an argument, the caller will see the change --- this
+obviates the need for two different argument passing mechanisms as in
+Pascal.
+
+
+\section{Python scopes and name spaces}
+
+Before introducing classes, I first have to tell you something about
+Python's scope rules. Class definitions play some neat tricks with
+name spaces, and you need to know how scopes and name spaces work to
+fully understand what's going on. Incidentally, knowledge about this
+subject is useful for any advanced Python programmer.
+
+Let's begin with some definitions.
+
+A {\em name space} is a mapping from names to objects. Most name
+spaces are currently implemented as Python dictionaries, but that's
+normally not noticeable in any way (except for performance), and it
+may change in the future. Examples of name spaces are: the set of
+built-in names (functions such as \verb\abs()\, and built-in exception
+names); the global names in a module; and the local names in a
+function invocation. In a sense the set of attributes of an object
+also form a name space. The important things to know about name
+spaces is that there is absolutely no relation between names in
+different name spaces; for instance, two different modules may both
+define a function ``maximize'' without confusion --- users of the
+modules must prefix it with the module name.
+
+By the way, I use the word {\em attribute} for any name following a
+dot --- for example, in the expression \verb\z.real\, \verb\real\ is
+an attribute of the object \verb\z\. Strictly speaking, references to
+names in modules are attribute references: in the expression
+\verb\modname.funcname\, \verb\modname\ is a module object and
+\verb\funcname\ is an attribute of it. In this case there happens to
+be a straightforward mapping between the module's attributes and the
+global names defined in the module: they share the same name space!%
+\footnote{
+ Except for one thing. Module objects have a secret read-only
+ attribute called {\tt __dict__} which returns the dictionary
+ used to implement the module's name space; the name
+ {\tt __dict__} is an attribute but not a global name.
+ Obviously, using this violates the abstraction of name space
+ implementation, and should be restricted to things like
+ post-mortem debuggers...
+}
+
+Attributes may be read-only or writable. In the latter case,
+assignment to attributes is possible. Module attributes are writable:
+you can write \verb\modname.the_answer = 42\. Writable attributes may
+also be deleted with the del statement, e.g.
+\verb\del modname.the_answer\.
+
+Name spaces are created at different moments and have different
+lifetimes. The name space containing the built-in names is created
+when the Python interpreter starts up, and is never deleted. The
+global name space for a module is created when the module definition
+is read in; normally, module name spaces also last until the
+interpreter quits. The statements executed by the top-level
+invocation of the interpreter, either read from a script file or
+interactively, are considered part of a module called \verb\__main__\,
+so they have their own global name space. (The built-in names
+actually also live in a module; this is called \verb\builtin\,
+although it should really have been called \verb\__builtin__\.)
+
+The local name space for a function is created when the function is
+called, and deleted when the function returns or raises an exception
+that is not handled within the function. (Actually, forgetting would
+be a better way to describe what actually happens.) Of course,
+recursive invocations each have their own local name space.
+
+A {\em scope} is a textual region of a Python program where a name space
+is directly accessible. ``Directly accessible'' here means that an
+unqualified reference to a name attempts to find the name in the name
+space.
+
+Although scopes are determined statically, they are used dynamically.
+At any time during execution, exactly three nested scopes are in use
+(i.e., exactly three name spaces are directly accessible): the
+innermost scope, which is searched first, contains the local names,
+the middle scope, searched next, contains the current module's global
+names, and the outermost scope (searched last) is the name space
+containing built-in names.
+
+Usually, the local scope references the local names of the (textually)
+current function. Outside functions, the the local scope references
+the same name space as the global scope: the module's name space.
+Class definitions place yet another name space in the local scope.
+
+It is important to realize that scopes are determined textually: the
+global scope of a function defined in a module is that module's name
+space, no matter from where or by what alias the function is called.
+On the other hand, the actual search for names is done dynamically, at
+run time --- however, the the language definition is evolving towards
+static name resolution, at ``compile'' time, so don't rely on dynamic
+name resolution! (In fact, local variables are already determined
+statically.)
+
+A special quirk of Python is that assignments always go into the
+innermost scope. Assignments do not copy data --- they just
+bind names to objects. The same is true for deletions: the statement
+\verb\del x\ removes the binding of x from the name space referenced by the
+local scope. In fact, all operations that introduce new names use the
+local scope: in particular, import statements and function definitions
+bind the module or function name in the local scope. (The
+\verb\global\ statement can be used to indicate that particular
+variables live in the global scope.)
+
+
+\section{A first look at classes}
+
+Classes introduce a little bit of new syntax, three new object types,
+and some new semantics.
+
+
+\subsection{Class definition syntax}
+
+The simplest form of class definition looks like this:
+
+\begin{verbatim}
+ class ClassName:
+ <statement-1>
+ .
+ .
+ .
+ <statement-N>
+\end{verbatim}
+
+Class definitions, like function definitions (\verb\def\ statements)
+must be executed before they have any effect. (You could conceivably
+place a class definition in a branch of an \verb\if\ statement, or
+inside a function.)
+
+In practice, the statements inside a class definition will usually be
+function definitions, but other statements are allowed, and sometimes
+useful --- we'll come back to this later. The function definitions
+inside a class normally have a peculiar form of argument list,
+dictated by the calling conventions for methods --- again, this is
+explained later.
+
+When a class definition is entered, a new name space is created, and
+used as the local scope --- thus, all assignments to local variables
+go into this new name space. In particular, function definitions bind
+the name of the new function here.
+
+When a class definition is left normally (via the end), a {\em class
+object} is created. This is basically a wrapper around the contents
+of the name space created by the class definition; we'll learn more
+about class objects in the next section. The original local scope
+(the one in effect just before the class definitions was entered) is
+reinstated, and the class object is bound here to class name given in
+the class definition header (ClassName in the example).
+
+
+\subsection{Class objects}
+
+Class objects support two kinds of operations: attribute references
+and instantiation.
+
+{\em Attribute references} use the standard syntax used for all
+attribute references in Python: \verb\obj.name\. Valid attribute
+names are all the names that were in the class's name space when the
+class object was created. So, if the class definition looked like
+this:
+
+\begin{verbatim}
+ class MyClass:
+ i = 12345
+ def f(x):
+ return 'hello world'
+\end{verbatim}
+
+then \verb\MyClass.i\ and \verb\MyClass.f\ are valid attribute
+references, returning an integer and a function object, respectively.
+Class attributes can also be assigned to, so you can change the
+value of \verb\MyClass.i\ by assignment.
+
+Class {\em instantiation} uses function notation. Just pretend that
+the class object is a parameterless function that returns a new
+instance of the class. For example, (assuming the above class):
+
+\begin{verbatim}
+ x = MyClass()
+\end{verbatim}
+
+creates a new {\em instance} of the class and assigns this object to
+the local variable \verb\x\.
+
+
+\subsection{Instance objects}
+
+Now what can we do with instance objects? The only operations
+understood by instance objects are attribute references. There are
+two kinds of valid attribute names.
+
+The first I'll call {\em data attributes}. These correspond to
+``instance variables'' in Smalltalk, and to ``data members'' in C++.
+Data attributes need not be declared; like local variables, they
+spring into existence when they are first assigned to. For example,
+if \verb\x\ in the instance of \verb\MyClass\ created above, the
+following piece of code will print the value 16, without leaving a
+trace:
+
+\begin{verbatim}
+ x.counter = 1
+ while x.counter < 10:
+ x.counter = x.counter * 2
+ print x.counter
+ del x.counter
+\end{verbatim}
+
+The second kind of attribute references understood by instance objects
+are {\em methods}. A method is a function that ``belongs to'' an
+object. (In Python, the term method is not unique to class instances:
+other object types can have methods as well, e.g., list objects have
+methods called append, insert, remove, sort, and so on. However,
+below, we'll use the term method exclusively to mean methods of class
+instance objects, unless explicitly stated otherwise.)
+
+Valid method names of an instance object depend on its class. By
+definition, all attributes of a class that are (user-defined) function
+objects define corresponding methods of its instances. So in our
+example, \verb\x.f\ is a valid method reference, since
+\verb\MyClass.f\ is a function, but \verb\x.i\ is not, since
+\verb\MyClass.i\ is not. But \verb\x.f\ is not the
+same thing as \verb\MyClass.f\ --- it is a {\em method object}, not a
+function object.
+
+
+\subsection{Method objects}
+
+Usually, a method is called immediately, e.g.:
+
+\begin{verbatim}
+ x.f()
+\end{verbatim}
+
+In our example, this will return the string \verb\'hello world'\.
+However, it is not necessary to call a method right away: \verb\x.f\
+is a method object, and can be stored away and called at a later
+moment, for example:
+
+\begin{verbatim}
+ xf = x.f
+ while 1:
+ print xf()
+\end{verbatim}
+
+will continue to print \verb\hello world\ until the end of time.
+
+What exactly happens when a method is called? You may have noticed
+that \verb\x.f()\ was called without an argument above, even though
+the function definition for \verb\f\ specified an argument. What
+happened to the argument? Surely Python raises an exception when a
+function that requires an argument is called without any --- even if
+the argument isn't actually used...
+
+Actually, you may have guessed the answer: the special thing about
+methods is that the object is passed as the first argument of the
+function. In our example, the call \verb\x.f()\ is exactly equivalent
+to \verb\MyClass.f(x)\. In general, calling a method with a list of
+{\em n} arguments is equivalent to calling the corresponding function
+with an argument list that is created by inserting the method's object
+before the first argument.
+
+If you still don't understand how methods work, a look at the
+implementation can perhaps clarify matters. When an instance
+attribute is referenced that isn't a data attribute, its class is
+searched. If the name denotes a valid class attribute that is a
+function object, a method object is created by packing (pointers to)
+the instance object and the function object just found together in an
+abstract object: this is the method object. When the method object is
+called with an argument list, it is unpacked again, a new argument
+list is constructed from the instance object and the original argument
+list, and the function object is called with this new argument list.
+
+
+\section{Random remarks}
+
+
+[These should perhaps be placed more carefully...]
+
+
+Data attributes override method attributes with the same name; to
+avoid accidental name conflicts, which may cause hard-to-find bugs in
+large programs, it is wise to use some kind of convention that
+minimizes the chance of conflicts, e.g., capitalize method names,
+prefix data attribute names with a small unique string (perhaps just
+an undescore), or use verbs for methods and nouns for data attributes.
+
+
+Data attributes may be referenced by methods as well as by ordinary
+users (``clients'') of an object. In other words, classes are not
+usable to implement pure abstract data types. In fact, nothing in
+Python makes it possible to enforce data hiding --- it is all based
+upon convention. (On the other hand, the Python implementation,
+written in C, can completely hide implementation details and control
+access to an object if necessary; this can be used by extensions to
+Python written in C.)
+
+
+Clients should use data attributes with care --- clients may mess up
+invariants maintained by the methods by stamping on their data
+attributes. Note that clients may add data attributes of their own to
+an instance object without affecting the validity of the methods, as
+long as name conflicts are avoided --- again, a naming convention can
+save a lot of headaches here.
+
+
+There is no shorthand for referencing data attributes (or other
+methods!) from within methods. I find that this actually increases
+the readability of methods: there is no chance of confusing local
+variables and instance variables when glancing through a method.
+
+
+Conventionally, the first argument of methods is often called
+\verb\self\. This is nothing more than a convention: the name
+\verb\self\ has absolutely no special meaning to Python. (Note,
+however, that by not following the convention your code may be less
+readable by other Python programmers, and it is also conceivable that
+a {\em class browser} program be written which relies upon such a
+convention.)
+
+
+Any function object that is a class attribute defines a method for
+instances of that class. It is not necessary that the function
+definition is textually enclosed in the class definition: assigning a
+function object to a local variable in the class is also ok. For
+example:
+
+\begin{verbatim}
+ # Function defined outside the class
+ def f1(self, x, y):
+ return min(x, x+y)
+
+ class C:
+ f = f1
+ def g(self):
+ return 'hello world'
+ h = g
+\end{verbatim}
+
+Now \verb\f\, \verb\g\ and \verb\h\ are all attributes of class
+\verb\C\ that refer to function objects, and consequently they are all
+methods of instances of \verb\C\ --- \verb\h\ being exactly equivalent
+to \verb\g\. Note that this practice usually only serves to confuse
+the reader of a program.
+
+
+Methods may call other methods by using method attributes of the
+\verb\self\ argument, e.g.:
+
+\begin{verbatim}
+ class Bag:
+ def empty(self):
+ self.data = []
+ def add(self, x):
+ self.data.append(x)
+ def addtwice(self, x):
+ self.add(x) self.add(x)
+\end{verbatim}
+
+
+The instantiation operation (``calling'' a class object) creates an
+empty object. Many classes like to create objects in a known initial
+state. There is no special syntax to enforce this, but a convention
+works almost as well: add a method named \verb\init\ to the class,
+which initializes the instance (by assigning to some important data
+attributes) and returns the instance itself. For example, class
+\verb\Bag\ above could have the following method:
+
+\begin{verbatim}
+ def init(self):
+ self.empty()
+ return self
+\end{verbatim}
+
+The client can then create and initialize an instance in one
+statement, as follows:
+
+\begin{verbatim}
+ x = Bag().init()
+\end{verbatim}
+
+Of course, the \verb\init\ method may have arguments for greater
+flexibility.
+
+Warning: a common mistake is to forget the \verb\return self\ at the
+end of an init method!
+
+
+Methods may reference global names in the same way as ordinary
+functions. The global scope associated with a method is the module
+containing the class definition. (The class itself is never used as a
+global scope!) While one rarely encounters a good reason for using
+global data in a method, there are many legitimate uses of the global
+scope: for one thing, functions and modules imported into the global
+scope can be used by methods, as well as functions and classes defined
+in it. Usually, the class containing the method is itself defined in
+this global scope, and in the next section we'll find some good
+reasons why a method would want to reference its own class!
+
+
+\section{Inheritance}
+
+Of course, a language feature would not be worthy of the name ``class''
+without supporting inheritance. The syntax for a derived class
+definition looks as follows:
+
+\begin{verbatim}
+ class DerivedClassName(BaseClassName):
+ <statement-1>
+ .
+ .
+ .
+ <statement-N>
+\end{verbatim}
+
+The name \verb\BaseClassName\ must be defined in a scope containing
+the derived class definition. Instead of a base class name, an
+expression is also allowed. This is useful when the base class is
+defined in another module, e.g.,
+
+\begin{verbatim}
+ class DerivedClassName(modname.BaseClassName):
+\end{verbatim}
+
+Execution of a derived class definition proceeds the same as for a
+base class. When the class object is constructed, the base class is
+remembered. This is used for resolving attribute references: if a
+requested attribute is not found in the class, it is searched in the
+base class. This rule is applied recursively if the base class itself
+is derived from some other class.
+
+There's nothing special about instantiation of derived classes:
+\verb\DerivedClassName()\ creates a new instance of the class. Method
+references are resolved as follows: the corresponding class attribute
+is searched, descending down the chain of base classes if necessary,
+and the method reference is valid if this yields a function object.
+
+Derived classes may override methods of their base classes. Because
+methods have no special privileges when calling other methods of the
+same object, a method of a base class that calls another method
+defined in the same base class, may in fact end up calling a method of
+a derived class that overrides it. (For C++ programmers: all methods
+in Python are ``virtual functions''.)
+
+An overriding method in a derived class may in fact want to extend
+rather than simply replace the base class method of the same name.
+There is a simple way to call the base class method directly: just
+call \verb\BaseClassName.methodname(self, arguments)\. This is
+occasionally useful to clients as well. (Note that this only works if
+the base class is defined or imported directly in the global scope.)
+
+
+\subsection{Multiple inheritance}
+
+Poython supports a limited form of multiple inheritance as well. A
+class definition with multiple base classes looks as follows:
+
+\begin{verbatim}
+ class DerivedClassName(Base1, Base2, Base3):
+ <statement-1>
+ .
+ .
+ .
+ <statement-N>
+\end{verbatim}
+
+The only rule necessary to explain the semantics is the resolution
+rule used for class attribute references. This is depth-first,
+left-to-right. Thus, if an attribute is not found in
+\verb\DerivedClassName\, it is searched in \verb\Base1\, then
+(recursively) in the base classes of \verb\Base1\, and only if it is
+not found there, it is searched in \verb\Base2\, and so on.
+
+(To some people breadth first --- searching \verb\Base2\ and
+\verb\Base3\ before the base classes of \verb\Base1\ --- looks more
+natural. However, this would require you to know whether a particular
+attribute of \verb\Base1\ is actually defined in \verb\Base1\ or in
+one of its base classes before you can figure out the consequences of
+a name conflict with an attribute of \verb\Base2\. The depth-first
+rule makes no differences between direct and inherited attributes of
+\verb\Base1\.)
+
+It is clear that indiscriminate use of multiple inheritance is a
+maintenance nightmare, given the reliance in Python on conventions to
+avoid accidental name conflicts. A well-known problem with multiple
+inheritance is a class derived from two classes that happen to have a
+common base class. While it is easy enough to figure out what happens
+in this case (the instance will have a single copy of ``instance
+variables'' or data attributes used by the common base class), it is
+not clear that these semantics are in any way useful.
+
+
+\section{Odds and ends}
+
+Sometimes it is useful to have a data type similar to the Pascal
+``record'' or C ``struct'', bundling together a couple of named data
+items. An empty class definition will do nicely, e.g.:
+
+\begin{verbatim}
+ class Employee:
+ pass
+
+ john = Employee() # Create an empty employee record
+
+ # Fill the fields of the record
+ john.name = 'John Doe'
+ john.dept = 'computer lab'
+ john.salary = 1000
+\end{verbatim}
+
+
+A piece of Python code that expects a particular abstract data type
+can often be passed a class that emulates the methods of that data
+type instead. For instance, if you have a function that formats some
+data from a file object, you can define a class with methods
+\verb\read()\ and \verb\readline()\ that gets the data from a string
+buffer instead, and pass it as an argument. (Unfortunately, this
+technique has its limitations: a class can't define operations that
+are accessed by special syntax such as sequence subscripting or
+arithmetic operators, and assigning such a ``pseudo-file'' to
+\verb\sys.stdin\ will not cause the interpreter to read further input
+from it.)
+
+
+Instance method objects have attributes, too: \verb\m.im_self\ is the
+object of which the method is an instance, and \verb\m.im_func\ is the
+function object corresponding to the method.
+
+
+XXX Mention bw compat hacks.
+
+
\end{document}
\pagenumbering{arabic}
+
\chapter{Whetting Your Appetite}
If you ever wrote a large shell script, you probably know this
reference material about built-in and standard types, functions and
modules that can save you a lot of time when writing Python programs.
+
\chapter{Using the Python Interpreter}
\section{Invoking the Interpreter}
command to check (or even suggest) matching parentheses, quotes etc.
would also be useful.
+
\chapter{An Informal Introduction to Python}
In the following examples, input and output are distinguished by the
\end{itemize}
+
\chapter{More Control Flow Tools}
Besides the {\tt while} statement just introduced, Python knows the
\end{itemize}
+
\chapter{Odds and Ends}
This chapter describes some things you've learned about already in
the language.
}
+
\chapter{Modules}
If you quit from the Python interpreter and enter it again, the
>>>
\end{verbatim}\ecode
+
\chapter{Output Formatting}
So far we've encountered two ways of writing values: {\em expression
>>>
\end{verbatim}\ecode
+
\chapter{Errors and Exceptions}
Until now error messages haven't been more than mentioned, but if you
It is also executed when the {\tt try} statement is left via a
{\tt break} or {\tt return} statement.
+
+\chapter{Classes}
+
+Python's class mechanism adds classes to the language with a minimum
+of new syntax and semantics. It is a mixture of the class mechanisms
+found in C++ and Modula-3. As is true for modules, classes in Python
+do not put an absolute barrier between definition and user, but rather
+rely on the politeness of the user not to ``break into the
+definition.'' The most important features of classes are retained
+with full power, however: the class inheritance mechanism allows
+multiple base classes, a derived class can override any methods of its
+base class(es), a method can call the method of a base class with the
+same name. Objects can contain an arbitrary amount of private data.
+
+In C++ terminology, all class members (including the data members) are
+{\em public}, and all member functions are {\em virtual}. There are
+no special constructors or desctructors. As in Modula-3, there are no
+shorthands for referencing the object's members from its methods: the
+method function is declared with an explicit first argument
+representing the object, which is provided implicitly by the call. As
+in Smalltalk, classes themselves are objects, albeit in the wider
+sense of the word: in Python, all data types are objects. This
+provides semantics for importing and renaming. But, just like in C++
+or Modula-3, built-in types cannot be used as base classes for
+extension by the user. Also, like in Modula-3 but unlike in C++, the
+built-in operators with special syntax (arithmetic operators,
+subscriptong etc.) cannot be redefined for class members.
+
+
+\section{A word about terminology}
+
+Lacking universally accepted terminology to talk about classes, I'll
+make occasional use of Smalltalk and C++ terms. (I'd use Modula-3
+terms, since its object-oriented semantics are closer to those of
+Python than C++, but I expect that few readers have heard of it...)
+
+I also have to warn you that there's a terminological pitfall for
+object-oriented readers: the word ``object'' in Python does not
+necessarily mean a class instance. Like C++ and Modula-3, and unlike
+Smalltalk, not all types in Python are classes: the basic built-in
+types like integers and lists aren't, and even somewhat more exotic
+types like files aren't. However, {\em all} Python types share a little
+bit of common semantics that is best described by using the word
+object.
+
+Objects have individuality, and multiple names (in multiple scopes)
+can be bound to the same object. This is known as aliasing in other
+languages. This is usually not appreciated on a first glance at
+Python, and can be safely ignored when dealing with immutable basic
+types (numbers, strings, tuples). However, aliasing has an
+(intended!) effect on the semantics of Python code involving mutable
+objects such as lists, dictionaries, and most types representing
+entities outside the program (files, windows, etc.). This is usually
+used to the benefit of the program, since aliases behave like pointers
+in some respects. For example, passing an object is cheap since only
+a pointer is passed by the implementation; and if a function modifies
+an object passed as an argument, the caller will see the change --- this
+obviates the need for two different argument passing mechanisms as in
+Pascal.
+
+
+\section{Python scopes and name spaces}
+
+Before introducing classes, I first have to tell you something about
+Python's scope rules. Class definitions play some neat tricks with
+name spaces, and you need to know how scopes and name spaces work to
+fully understand what's going on. Incidentally, knowledge about this
+subject is useful for any advanced Python programmer.
+
+Let's begin with some definitions.
+
+A {\em name space} is a mapping from names to objects. Most name
+spaces are currently implemented as Python dictionaries, but that's
+normally not noticeable in any way (except for performance), and it
+may change in the future. Examples of name spaces are: the set of
+built-in names (functions such as \verb\abs()\, and built-in exception
+names); the global names in a module; and the local names in a
+function invocation. In a sense the set of attributes of an object
+also form a name space. The important things to know about name
+spaces is that there is absolutely no relation between names in
+different name spaces; for instance, two different modules may both
+define a function ``maximize'' without confusion --- users of the
+modules must prefix it with the module name.
+
+By the way, I use the word {\em attribute} for any name following a
+dot --- for example, in the expression \verb\z.real\, \verb\real\ is
+an attribute of the object \verb\z\. Strictly speaking, references to
+names in modules are attribute references: in the expression
+\verb\modname.funcname\, \verb\modname\ is a module object and
+\verb\funcname\ is an attribute of it. In this case there happens to
+be a straightforward mapping between the module's attributes and the
+global names defined in the module: they share the same name space!%
+\footnote{
+ Except for one thing. Module objects have a secret read-only
+ attribute called {\tt __dict__} which returns the dictionary
+ used to implement the module's name space; the name
+ {\tt __dict__} is an attribute but not a global name.
+ Obviously, using this violates the abstraction of name space
+ implementation, and should be restricted to things like
+ post-mortem debuggers...
+}
+
+Attributes may be read-only or writable. In the latter case,
+assignment to attributes is possible. Module attributes are writable:
+you can write \verb\modname.the_answer = 42\. Writable attributes may
+also be deleted with the del statement, e.g.
+\verb\del modname.the_answer\.
+
+Name spaces are created at different moments and have different
+lifetimes. The name space containing the built-in names is created
+when the Python interpreter starts up, and is never deleted. The
+global name space for a module is created when the module definition
+is read in; normally, module name spaces also last until the
+interpreter quits. The statements executed by the top-level
+invocation of the interpreter, either read from a script file or
+interactively, are considered part of a module called \verb\__main__\,
+so they have their own global name space. (The built-in names
+actually also live in a module; this is called \verb\builtin\,
+although it should really have been called \verb\__builtin__\.)
+
+The local name space for a function is created when the function is
+called, and deleted when the function returns or raises an exception
+that is not handled within the function. (Actually, forgetting would
+be a better way to describe what actually happens.) Of course,
+recursive invocations each have their own local name space.
+
+A {\em scope} is a textual region of a Python program where a name space
+is directly accessible. ``Directly accessible'' here means that an
+unqualified reference to a name attempts to find the name in the name
+space.
+
+Although scopes are determined statically, they are used dynamically.
+At any time during execution, exactly three nested scopes are in use
+(i.e., exactly three name spaces are directly accessible): the
+innermost scope, which is searched first, contains the local names,
+the middle scope, searched next, contains the current module's global
+names, and the outermost scope (searched last) is the name space
+containing built-in names.
+
+Usually, the local scope references the local names of the (textually)
+current function. Outside functions, the the local scope references
+the same name space as the global scope: the module's name space.
+Class definitions place yet another name space in the local scope.
+
+It is important to realize that scopes are determined textually: the
+global scope of a function defined in a module is that module's name
+space, no matter from where or by what alias the function is called.
+On the other hand, the actual search for names is done dynamically, at
+run time --- however, the the language definition is evolving towards
+static name resolution, at ``compile'' time, so don't rely on dynamic
+name resolution! (In fact, local variables are already determined
+statically.)
+
+A special quirk of Python is that assignments always go into the
+innermost scope. Assignments do not copy data --- they just
+bind names to objects. The same is true for deletions: the statement
+\verb\del x\ removes the binding of x from the name space referenced by the
+local scope. In fact, all operations that introduce new names use the
+local scope: in particular, import statements and function definitions
+bind the module or function name in the local scope. (The
+\verb\global\ statement can be used to indicate that particular
+variables live in the global scope.)
+
+
+\section{A first look at classes}
+
+Classes introduce a little bit of new syntax, three new object types,
+and some new semantics.
+
+
+\subsection{Class definition syntax}
+
+The simplest form of class definition looks like this:
+
+\begin{verbatim}
+ class ClassName:
+ <statement-1>
+ .
+ .
+ .
+ <statement-N>
+\end{verbatim}
+
+Class definitions, like function definitions (\verb\def\ statements)
+must be executed before they have any effect. (You could conceivably
+place a class definition in a branch of an \verb\if\ statement, or
+inside a function.)
+
+In practice, the statements inside a class definition will usually be
+function definitions, but other statements are allowed, and sometimes
+useful --- we'll come back to this later. The function definitions
+inside a class normally have a peculiar form of argument list,
+dictated by the calling conventions for methods --- again, this is
+explained later.
+
+When a class definition is entered, a new name space is created, and
+used as the local scope --- thus, all assignments to local variables
+go into this new name space. In particular, function definitions bind
+the name of the new function here.
+
+When a class definition is left normally (via the end), a {\em class
+object} is created. This is basically a wrapper around the contents
+of the name space created by the class definition; we'll learn more
+about class objects in the next section. The original local scope
+(the one in effect just before the class definitions was entered) is
+reinstated, and the class object is bound here to class name given in
+the class definition header (ClassName in the example).
+
+
+\subsection{Class objects}
+
+Class objects support two kinds of operations: attribute references
+and instantiation.
+
+{\em Attribute references} use the standard syntax used for all
+attribute references in Python: \verb\obj.name\. Valid attribute
+names are all the names that were in the class's name space when the
+class object was created. So, if the class definition looked like
+this:
+
+\begin{verbatim}
+ class MyClass:
+ i = 12345
+ def f(x):
+ return 'hello world'
+\end{verbatim}
+
+then \verb\MyClass.i\ and \verb\MyClass.f\ are valid attribute
+references, returning an integer and a function object, respectively.
+Class attributes can also be assigned to, so you can change the
+value of \verb\MyClass.i\ by assignment.
+
+Class {\em instantiation} uses function notation. Just pretend that
+the class object is a parameterless function that returns a new
+instance of the class. For example, (assuming the above class):
+
+\begin{verbatim}
+ x = MyClass()
+\end{verbatim}
+
+creates a new {\em instance} of the class and assigns this object to
+the local variable \verb\x\.
+
+
+\subsection{Instance objects}
+
+Now what can we do with instance objects? The only operations
+understood by instance objects are attribute references. There are
+two kinds of valid attribute names.
+
+The first I'll call {\em data attributes}. These correspond to
+``instance variables'' in Smalltalk, and to ``data members'' in C++.
+Data attributes need not be declared; like local variables, they
+spring into existence when they are first assigned to. For example,
+if \verb\x\ in the instance of \verb\MyClass\ created above, the
+following piece of code will print the value 16, without leaving a
+trace:
+
+\begin{verbatim}
+ x.counter = 1
+ while x.counter < 10:
+ x.counter = x.counter * 2
+ print x.counter
+ del x.counter
+\end{verbatim}
+
+The second kind of attribute references understood by instance objects
+are {\em methods}. A method is a function that ``belongs to'' an
+object. (In Python, the term method is not unique to class instances:
+other object types can have methods as well, e.g., list objects have
+methods called append, insert, remove, sort, and so on. However,
+below, we'll use the term method exclusively to mean methods of class
+instance objects, unless explicitly stated otherwise.)
+
+Valid method names of an instance object depend on its class. By
+definition, all attributes of a class that are (user-defined) function
+objects define corresponding methods of its instances. So in our
+example, \verb\x.f\ is a valid method reference, since
+\verb\MyClass.f\ is a function, but \verb\x.i\ is not, since
+\verb\MyClass.i\ is not. But \verb\x.f\ is not the
+same thing as \verb\MyClass.f\ --- it is a {\em method object}, not a
+function object.
+
+
+\subsection{Method objects}
+
+Usually, a method is called immediately, e.g.:
+
+\begin{verbatim}
+ x.f()
+\end{verbatim}
+
+In our example, this will return the string \verb\'hello world'\.
+However, it is not necessary to call a method right away: \verb\x.f\
+is a method object, and can be stored away and called at a later
+moment, for example:
+
+\begin{verbatim}
+ xf = x.f
+ while 1:
+ print xf()
+\end{verbatim}
+
+will continue to print \verb\hello world\ until the end of time.
+
+What exactly happens when a method is called? You may have noticed
+that \verb\x.f()\ was called without an argument above, even though
+the function definition for \verb\f\ specified an argument. What
+happened to the argument? Surely Python raises an exception when a
+function that requires an argument is called without any --- even if
+the argument isn't actually used...
+
+Actually, you may have guessed the answer: the special thing about
+methods is that the object is passed as the first argument of the
+function. In our example, the call \verb\x.f()\ is exactly equivalent
+to \verb\MyClass.f(x)\. In general, calling a method with a list of
+{\em n} arguments is equivalent to calling the corresponding function
+with an argument list that is created by inserting the method's object
+before the first argument.
+
+If you still don't understand how methods work, a look at the
+implementation can perhaps clarify matters. When an instance
+attribute is referenced that isn't a data attribute, its class is
+searched. If the name denotes a valid class attribute that is a
+function object, a method object is created by packing (pointers to)
+the instance object and the function object just found together in an
+abstract object: this is the method object. When the method object is
+called with an argument list, it is unpacked again, a new argument
+list is constructed from the instance object and the original argument
+list, and the function object is called with this new argument list.
+
+
+\section{Random remarks}
+
+
+[These should perhaps be placed more carefully...]
+
+
+Data attributes override method attributes with the same name; to
+avoid accidental name conflicts, which may cause hard-to-find bugs in
+large programs, it is wise to use some kind of convention that
+minimizes the chance of conflicts, e.g., capitalize method names,
+prefix data attribute names with a small unique string (perhaps just
+an undescore), or use verbs for methods and nouns for data attributes.
+
+
+Data attributes may be referenced by methods as well as by ordinary
+users (``clients'') of an object. In other words, classes are not
+usable to implement pure abstract data types. In fact, nothing in
+Python makes it possible to enforce data hiding --- it is all based
+upon convention. (On the other hand, the Python implementation,
+written in C, can completely hide implementation details and control
+access to an object if necessary; this can be used by extensions to
+Python written in C.)
+
+
+Clients should use data attributes with care --- clients may mess up
+invariants maintained by the methods by stamping on their data
+attributes. Note that clients may add data attributes of their own to
+an instance object without affecting the validity of the methods, as
+long as name conflicts are avoided --- again, a naming convention can
+save a lot of headaches here.
+
+
+There is no shorthand for referencing data attributes (or other
+methods!) from within methods. I find that this actually increases
+the readability of methods: there is no chance of confusing local
+variables and instance variables when glancing through a method.
+
+
+Conventionally, the first argument of methods is often called
+\verb\self\. This is nothing more than a convention: the name
+\verb\self\ has absolutely no special meaning to Python. (Note,
+however, that by not following the convention your code may be less
+readable by other Python programmers, and it is also conceivable that
+a {\em class browser} program be written which relies upon such a
+convention.)
+
+
+Any function object that is a class attribute defines a method for
+instances of that class. It is not necessary that the function
+definition is textually enclosed in the class definition: assigning a
+function object to a local variable in the class is also ok. For
+example:
+
+\begin{verbatim}
+ # Function defined outside the class
+ def f1(self, x, y):
+ return min(x, x+y)
+
+ class C:
+ f = f1
+ def g(self):
+ return 'hello world'
+ h = g
+\end{verbatim}
+
+Now \verb\f\, \verb\g\ and \verb\h\ are all attributes of class
+\verb\C\ that refer to function objects, and consequently they are all
+methods of instances of \verb\C\ --- \verb\h\ being exactly equivalent
+to \verb\g\. Note that this practice usually only serves to confuse
+the reader of a program.
+
+
+Methods may call other methods by using method attributes of the
+\verb\self\ argument, e.g.:
+
+\begin{verbatim}
+ class Bag:
+ def empty(self):
+ self.data = []
+ def add(self, x):
+ self.data.append(x)
+ def addtwice(self, x):
+ self.add(x) self.add(x)
+\end{verbatim}
+
+
+The instantiation operation (``calling'' a class object) creates an
+empty object. Many classes like to create objects in a known initial
+state. There is no special syntax to enforce this, but a convention
+works almost as well: add a method named \verb\init\ to the class,
+which initializes the instance (by assigning to some important data
+attributes) and returns the instance itself. For example, class
+\verb\Bag\ above could have the following method:
+
+\begin{verbatim}
+ def init(self):
+ self.empty()
+ return self
+\end{verbatim}
+
+The client can then create and initialize an instance in one
+statement, as follows:
+
+\begin{verbatim}
+ x = Bag().init()
+\end{verbatim}
+
+Of course, the \verb\init\ method may have arguments for greater
+flexibility.
+
+Warning: a common mistake is to forget the \verb\return self\ at the
+end of an init method!
+
+
+Methods may reference global names in the same way as ordinary
+functions. The global scope associated with a method is the module
+containing the class definition. (The class itself is never used as a
+global scope!) While one rarely encounters a good reason for using
+global data in a method, there are many legitimate uses of the global
+scope: for one thing, functions and modules imported into the global
+scope can be used by methods, as well as functions and classes defined
+in it. Usually, the class containing the method is itself defined in
+this global scope, and in the next section we'll find some good
+reasons why a method would want to reference its own class!
+
+
+\section{Inheritance}
+
+Of course, a language feature would not be worthy of the name ``class''
+without supporting inheritance. The syntax for a derived class
+definition looks as follows:
+
+\begin{verbatim}
+ class DerivedClassName(BaseClassName):
+ <statement-1>
+ .
+ .
+ .
+ <statement-N>
+\end{verbatim}
+
+The name \verb\BaseClassName\ must be defined in a scope containing
+the derived class definition. Instead of a base class name, an
+expression is also allowed. This is useful when the base class is
+defined in another module, e.g.,
+
+\begin{verbatim}
+ class DerivedClassName(modname.BaseClassName):
+\end{verbatim}
+
+Execution of a derived class definition proceeds the same as for a
+base class. When the class object is constructed, the base class is
+remembered. This is used for resolving attribute references: if a
+requested attribute is not found in the class, it is searched in the
+base class. This rule is applied recursively if the base class itself
+is derived from some other class.
+
+There's nothing special about instantiation of derived classes:
+\verb\DerivedClassName()\ creates a new instance of the class. Method
+references are resolved as follows: the corresponding class attribute
+is searched, descending down the chain of base classes if necessary,
+and the method reference is valid if this yields a function object.
+
+Derived classes may override methods of their base classes. Because
+methods have no special privileges when calling other methods of the
+same object, a method of a base class that calls another method
+defined in the same base class, may in fact end up calling a method of
+a derived class that overrides it. (For C++ programmers: all methods
+in Python are ``virtual functions''.)
+
+An overriding method in a derived class may in fact want to extend
+rather than simply replace the base class method of the same name.
+There is a simple way to call the base class method directly: just
+call \verb\BaseClassName.methodname(self, arguments)\. This is
+occasionally useful to clients as well. (Note that this only works if
+the base class is defined or imported directly in the global scope.)
+
+
+\subsection{Multiple inheritance}
+
+Poython supports a limited form of multiple inheritance as well. A
+class definition with multiple base classes looks as follows:
+
+\begin{verbatim}
+ class DerivedClassName(Base1, Base2, Base3):
+ <statement-1>
+ .
+ .
+ .
+ <statement-N>
+\end{verbatim}
+
+The only rule necessary to explain the semantics is the resolution
+rule used for class attribute references. This is depth-first,
+left-to-right. Thus, if an attribute is not found in
+\verb\DerivedClassName\, it is searched in \verb\Base1\, then
+(recursively) in the base classes of \verb\Base1\, and only if it is
+not found there, it is searched in \verb\Base2\, and so on.
+
+(To some people breadth first --- searching \verb\Base2\ and
+\verb\Base3\ before the base classes of \verb\Base1\ --- looks more
+natural. However, this would require you to know whether a particular
+attribute of \verb\Base1\ is actually defined in \verb\Base1\ or in
+one of its base classes before you can figure out the consequences of
+a name conflict with an attribute of \verb\Base2\. The depth-first
+rule makes no differences between direct and inherited attributes of
+\verb\Base1\.)
+
+It is clear that indiscriminate use of multiple inheritance is a
+maintenance nightmare, given the reliance in Python on conventions to
+avoid accidental name conflicts. A well-known problem with multiple
+inheritance is a class derived from two classes that happen to have a
+common base class. While it is easy enough to figure out what happens
+in this case (the instance will have a single copy of ``instance
+variables'' or data attributes used by the common base class), it is
+not clear that these semantics are in any way useful.
+
+
+\section{Odds and ends}
+
+Sometimes it is useful to have a data type similar to the Pascal
+``record'' or C ``struct'', bundling together a couple of named data
+items. An empty class definition will do nicely, e.g.:
+
+\begin{verbatim}
+ class Employee:
+ pass
+
+ john = Employee() # Create an empty employee record
+
+ # Fill the fields of the record
+ john.name = 'John Doe'
+ john.dept = 'computer lab'
+ john.salary = 1000
+\end{verbatim}
+
+
+A piece of Python code that expects a particular abstract data type
+can often be passed a class that emulates the methods of that data
+type instead. For instance, if you have a function that formats some
+data from a file object, you can define a class with methods
+\verb\read()\ and \verb\readline()\ that gets the data from a string
+buffer instead, and pass it as an argument. (Unfortunately, this
+technique has its limitations: a class can't define operations that
+are accessed by special syntax such as sequence subscripting or
+arithmetic operators, and assigning such a ``pseudo-file'' to
+\verb\sys.stdin\ will not cause the interpreter to read further input
+from it.)
+
+
+Instance method objects have attributes, too: \verb\m.im_self\ is the
+object of which the method is an instance, and \verb\m.im_func\ is the
+function object corresponding to the method.
+
+
+XXX Mention bw compat hacks.
+
+
\end{document}
projects / thirdparty / Python / cpython.git / commitdiff
