[Python-checkins] cpython (3.4): Issue #11974: Add tutorial section on class and instance variables

[raymond.hettinger]

http://hg.python.org/cpython/rev/8e5e04a1497f
changeset:   91356:8e5e04a1497f
branch:      3.4
parent:      91348:cc0f5d6ccb70
user:        Raymond Hettinger <python at rcn.com>
date:        Mon Jun 23 18:08:01 2014 -0700
summary:
  Issue #11974:  Add tutorial section on class and instance variables
(Based on a patch from Renee Chu.)

files:
  Doc/tutorial/classes.rst |  71 ++++++++++++++++++++++++++++
  Misc/ACKS                |   1 +
  2 files changed, 72 insertions(+), 0 deletions(-)


diff --git a/Doc/tutorial/classes.rst b/Doc/tutorial/classes.rst
--- a/Doc/tutorial/classes.rst
+++ b/Doc/tutorial/classes.rst
@@ -387,6 +387,77 @@
 argument list.
 
 
+.. _tut-class-and-instance-variables:
+
+Class and Instance Variables
+----------------------------
+
+Generally speaking, instance variables are for data unique to each instance
+and class variables are for attributes and methods shared by all instances
+of the class::
+
+    class Dog:
+
+        kind = 'canine'         # class variable shared by all instances
+
+        def __init__(self, name):
+            self.name = name    # instance variable unique to each instance
+
+    >>> d = Dog('Fido')
+    >>> e = Dog('Buddy')
+    >>> d.kind                  # shared by all dogs
+    'canine'
+    >>> e.kind                  # shared by all dogs
+    'canine'
+    >>> d.name                  # unique to d
+    'Fido'
+    >>> e.name                  # unique to e
+    'Buddy'
+
+As discussed in :ref:`tut-object`, shared data can have possibly surprising
+effects with involving :term:`mutable` objects such as lists and dictionaries.
+For example, the *tricks* list in the following code should not be used as a
+class variable because just a single list would be shared by all *Dog*
+instances::
+
+    class Dog:
+
+        tricks = []             # mistaken use of a class variable
+
+        def __init__(self, name):
+            self.name = name
+
+        def add_trick(self, trick):
+            self.tricks.append(trick)
+
+    >>> d = Dog('Fido')
+    >>> e = Dog('Buddy')
+    >>> d.add_trick('roll over')
+    >>> e.add_trick('play dead')
+    >>> d.tricks                # unexpectedly shared by all dogs
+    ['roll over', 'play dead']
+
+Correct design of the class should use an instance variable instead::
+
+    class Dog:
+
+        def __init__(self, name):
+            self.name = name
+            self.tricks = []    # creates a new empty list for each dog
+
+        def add_trick(self, trick):
+            self.tricks.append(trick)
+
+    >>> d = Dog('Fido')
+    >>> e = Dog('Buddy')
+    >>> d.add_trick('roll over')
+    >>> e.add_trick('play dead')
+    >>> d.tricks
+    ['roll over']
+    >>> e.tricks
+    ['play dead']
+
+
 .. _tut-remarks:
 
 Random Remarks
diff --git a/Misc/ACKS b/Misc/ACKS
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -238,6 +238,7 @@
 Lita Cho
 Anders Chrigström
 Tom Christiansen
+Renee Chu
 Vadim Chugunov
 Mauro Cicognini
 David Cinege

-- 
Repository URL: http://hg.python.org/cpython