class X:    pass

>>> X.__class__<class 'type'>>>> X.__class__.__base__<class 'object'>

class Rectangle:    def area( self ):        return self.length * self.width

>>> r= Rectangle()>>> r.length, r.width = 13, 8>>> r.area()104

"Explicit is better than implicit."

Tip

Pretty Poor Polymorphism

There's a fine line between flexibility and foolishness.

We may have stepped over the edge offflexible intofoolish as soon as we feel the need to write:

if 'x' in self.__dict__:

Or:

try:    self.xexcept AttributeError:

It's time to reconsider the API and add a common method or attribute. Refactoring is better than addingif statements.

class Card:    def  __init__( self, rank, suit ):        self.suit= suit        self.rank= rank        self.hard, self.soft = self._points()class NumberCard( Card ):    def _points( self ):        return int(self.rank), int(self.rank)class AceCard( Card ):    def _points( self ):        return 1, 11class FaceCard( Card ):    def _points( self ):        return 10, 10

cards = [ AceCard('A', '♠'), NumberCard('2','♠'), NumberCard('3','♠'), ]

class Suit:    def __init__( self, name, symbol ):        self.name= name        self.symbol= symbol

Club, Diamond, Heart, Spade = Suit('Club','♣'), Suit('Diamond','♦'), Suit('Heart','♥'), Suit('Spade','♠')

cards = [ AceCard('A', Spade), NumberCard('2', Spade), NumberCard('3', Spade), ]

Tip

The irrelevance of immutability

Immutability can become an attractive nuisance. It's sometimes justified by the mythical "malicious programmer" who modifies the constant value in their application. As a design consideration, this is silly. This mythical, malicious programmer can't be stopped this way. There's no easy way to "idiot-proof" code in Python. The malicious programmer has access to the source and can tweak it just as easily as they can write code to modify a constant.

It's better not to struggle too long to define the classes of immutable objects. InChapter 3,Attribute Access, Properties, and Descriptors, we'll show ways to implement immutability that provides suitable diagnostic information for a buggy program.

• We define a function that creates objects of the required classes.

• We define a class that has methods for creating objects. This is the full factory design pattern, as described in books on design patterns. In languages such as Java, a factory class hierarchy is required because the language doesn't support standalone functions.

Note

While this is a book about object-oriented programming, a function really is fine. It's common, idiomatic Python.

def card( rank, suit ):    if rank == 1: return AceCard( 'A', suit )    elif 2 <= rank < 11: return NumberCard( str(rank), suit )    elif 11 <= rank < 14:        name = { 11: 'J', 12: 'Q', 13: 'K' }[rank]        return FaceCard( name, suit )    else:        raise Exception( "Rank out of range" )

deck = [card(rank, suit)    for rank in range(1,14)        for suit in (Club, Diamond, Heart, Spade)]

Note the structure of theif statement in thecard() function. We did not use a catch-allelse clause to do any processing; we merely raised an exception. The use of a catch-allelse clause is subject to a tiny scrap of debate.

On the one hand, it can be argued that the condition that belongs on anelse clause should never be left unstated because it may hide subtle design errors. On the other hand, someelse clause conditions are truly obvious.

It's important to avoid the vagueelse clause.

Consider the following variant on this factory function definition:

def card2( rank, suit ):    if rank == 1: return AceCard( 'A', suit )    elif 2 <= rank < 11: return NumberCard( str(rank), suit )    else:        name = { 11: 'J', 12: 'Q', 13: 'K' }[rank]        return FaceCard( name, suit )

The following is what will happen when we try to build a deck:

deck2 = [card2(rank, suit) for rank in range(13) for suit in (Club, Diamond, Heart, Spade)]

Does it work? What if theif conditions were more complex?

Someprogrammers can understand thisif statement at aglance. Others will struggle to determine if all of the cases are properly exclusive.

For advanced Python programming, we should not leave it to the reader to deduce the conditions that apply to anelse clause. Either the condition should be obvious to the newest of n00bz, or it should be explicit.

Our factory function,card(), is a mixture of two very common factory design patterns:


For thesake of simplicity, it's better to focus on just one of these techniques rather than on both.

We can always replace a mapping withelif conditions. (Yes, always. The reverse is not true though; transformingelif conditions to a mapping can be challenging.)

The following is aCard factory without the mapping:

def card3( rank, suit ):    if rank == 1: return AceCard( 'A', suit )    elif 2 <= rank < 11: return NumberCard( str(rank), suit )    elif rank == 11:        return FaceCard( 'J', suit )    elif rank == 12:        return FaceCard( 'Q', suit )    elif rank == 13:        return FaceCard( 'K', suit )    else:        raise Exception( "Rank out of range" )

We rewrote thecard() factory function. The mapping was transformed into additionalelif clauses. Thisfunction has the advantage that it is more consistent than the previous version.

In some cases, we can use a mapping instead of a chain ofelif conditions. It's possible to findconditions that are so complex that a chain ofelif conditions is the only sensible way to express them. For simple cases, however, a mappingoften works better and can be easy to read.

Sinceclass is a first-class object, we can easily map from therank parameter to the class that must be constructed.

The following is aCard factory that uses only a mapping:

def card4( rank, suit ):    class_= {1: AceCard, 11: FaceCard, 12: FaceCard,        13: FaceCard}.get(rank, NumberCard)    return class_( rank, suit )

We've mapped therank object to a class. Then, we applied the class to therank andsuit values to build the finalCard instance.

We can use adefaultdict class as well. However, it's no simpler for a trivial static mapping. It looks like the following code snippet:

defaultdict( lambda: NumberCard, {1: AceCard, 11: FaceCard, 12: FaceCard, 12: FaceCard} )

Note that thedefault of adefaultdict class must be a function of zero arguments. We've used alambda construct to create the necessary function wrapper around a constant. This function, however, has a serious deficiency. It lacks the translation from1 toA and13 toK that we had in previous versions. When we try to add that feature, we run into a problem.

We need to change the mapping to provide both aCard subclass as well as the string version of therank object. What can we do for this two-part mapping? There are four common solutions:

We'lllookat each of these with a concrete example.

class_= {1: AceCard, 11: FaceCard, 12: FaceCard, 13: FaceCard }.get(rank, NumberCard)rank_str= {1:'A', 11:'J', 12:'Q', 13:'K'}.get(rank,str(rank))return class_( rank_str, suit )

class_, rank_str= {    1:  (AceCard,'A'),    11: (FaceCard,'J'),    12: (FaceCard,'Q'),    13: (FaceCard,'K'),    }.get(rank, (NumberCard, str(rank)))return class_( rank_str, suit )

from functools import partialpart_class= {    1:  partial(AceCard,'A'),    11: partial(FaceCard,'J'),    12: partial(FaceCard,'Q'),    13: partial(FaceCard,'K'),    }.get(rank, partial(NumberCard, str(rank)))return part_class( suit )

class CardFactory:    def rank( self, rank ):        self.class_, self.rank_str= {            1:(AceCard,'A'),            11:(FaceCard,'J'),            12:(FaceCard,'Q'),            13:(FaceCard,'K'),            }.get(rank, (NumberCard, str(rank)))        return self    def suit( self, suit ):        return self.class_( self.rank_str, suit )

card8 = CardFactory()deck8 = [card8.rank(r+1).suit(s) for r in range(13) for s in (Club, Diamond, Heart, Spade)]

class Card:    passclass NumberCard( Card ):    def  __init__( self, rank, suit ):        self.suit= suit        self.rank= str(rank)        self.hard = self.soft = rankclass AceCard( Card ):    def  __init__( self, rank, suit ):        self.suit= suit        self.rank= "A"        self.hard, self.soft =  1, 11class FaceCard( Card ):    def  __init__( self, rank, suit ):        self.suit= suit        self.rank= {11: 'J', 12: 'Q', 13: 'K' }[rank]        self.hard = self.soft = 10

class Card:    def __init__( self, rank, suit, hard, soft ):        self.rank= rank        self.suit= suit        self.hard= hard        self.soft= softclass NumberCard( Card ):    def  __init__( self, rank, suit ):        super().__init__( str(rank), suit, rank, rank )class AceCard( Card ):    def  __init__( self, rank, suit ):        super().__init__( "A", suit, 1, 11 )class FaceCard( Card ):    def  __init__( self, rank, suit ):        super().__init__( {11: 'J', 12: 'Q', 13: 'K' }[rank], suit, 10, 10 )

def card10( rank, suit ):    if rank == 1: return AceCard( rank, suit )    elif 2 <= rank < 11: return NumberCard( rank, suit )    elif 11 <= rank < 14: return FaceCard( rank, suit )    else:        raise Exception( "Rank out of range" )

Tip

Factory functions encapsulate complexity

There's a trade-off that occurs between sophisticated__init__() methods and factory functions. It's often better to stick with more direct but less programmer-friendly__init__() methods and push the complexity into factory functions. A factory function works well if you wish to wrap and encapsulate the construction complexities.

d= [card6(r+1,s) for r in range(13) for s in (Club, Diamond, Heart, Spade)]random.shuffle(d)hand= [ d.pop(), d.pop() ]

• Wrap: This design pattern is an existing collection definition. This might be an example of theFacade design pattern.

• Extend: This design pattern is an existing collection class. This is ordinary subclass definition.

• Invent: This is designed from scratch. We'll look at this inChapter 6,Creating Containers and Collections.

Thefollowing is a wrapper design thatcontains an internal collection:

class Deck:    def __init__( self ):        self._cards = [card6(r+1,s) for r in range(13) for s in (Club, Diamond, Heart, Spade)]        random.shuffle( self._cards )    def pop( self ):        return self._cards.pop()

We've definedDeck so that the internal collection is alist object. Thepop() method ofDeck simply delegates to the wrappedlist object.

We can then create aHand instance with the following kind of code:

d= Deck()hand= [ d.pop(), d.pop() ]

Generally, a Facade design pattern or wrapper class contains methods that are simply delegated to the underlying implementation class. This delegation can become wordy. For a sophisticated collection, we may wind up delegating a large number of methods to the wrapped object.

An alternative to wrapping is to extend a built-in class. By doing this, we have the advantage of not having to reimplement thepop() method; we can simply inherit it.

Thepop() method has the advantage that it creates a class without writing too much code. Inthis example, extending thelist class has the disadvantage that this provides many more functions than we truly need.

The following is a definition ofDeck that extends the built-inlist:

class Deck2( list ):    def __init__( self ):        super().__init__( card6(r+1,s) for r in range(13) for s in (Club, Diamond, Heart, Spade) )        random.shuffle( self )

In some cases, our methods will have to explicitly use the superclass methods in order to have proper class behavior. We'll see other examples of this in the following sections.

We leverage the superclass's__init__() method to populate ourlist object with an initial single deck of cards. Then we shuffle the cards. Thepop() method is simply inherited fromlist and works perfectly. Other methods inherited from thelist also work.

In a casino, the cards are often dealt from a shoe that has half a dozen decks of cards all mingled together. This considerationmakes it necessary for us to build our own version ofDeck and not simply use an unadornedlist object.

Additionally, a casino shoe is not dealt fully. Instead, a marker card is inserted. Because of the marker, some cards are effectively set aside and not used for play.

The following isDeck definition that contains multiple sets of 52-card decks:

class Deck3(list):    def __init__(self, decks=1):        super().__init__()        for i in range(decks):            self.extend( card6(r+1,s) for r in range(13) for s in (Club, Diamond, Heart, Spade) )        random.shuffle( self )        burn= random.randint(1,52)        for i in range(burn): self.pop()

Here, we used the__init__() superclass to build an empty collection. Then, we usedself.extend() to append multiple 52-card decks to the shoe. We could also usesuper().extend() since we did not provide an overriding implementation in this class.

Wecould also carry out the entire taskviasuper().__init__() using a more deeply nested generator expression, as shown in the following code snippet:

( card6(r+1,s) for r in range(13) for s in (Club, Diamond, Heart, Spade) for d in range(decks) )

This class provides us with a collection ofCard instances that we can use to emulate casino blackjack as dealt from a shoe.

There's a peculiar ritual in a casino where they reveal the burned card. If we're going to design a card-counting player strategy, we might want to emulate this nuance too.

class Hand:    def __init__( self, dealer_card ):        self.dealer_card= dealer_card        self.cards= []    def hard_total(self ):        return sum(c.hard for c in self.cards)    def soft_total(self ):        return sum(c.soft for c in self.cards)

d = Deck()h = Hand( d.pop() )h.cards.append( d.pop() )h.cards.append( d.pop() )

Ideally, the__init__() initializer method will create a complete instance of an object. This is a bitmore complex when creating a complete instance of a container that contains an internal collection of other objects. It'll be helpful if we can build this composite in a single step.

It's common to have both a method to incrementally accrete items as well as the initializer special method that can load all of the items in one step.

For example, we might have a class such as the following code snippet:

class Hand2:    def __init__( self, dealer_card, *cards ):        self.dealer_card= dealer_card        self.cards = list(cards)    def hard_total(self ):        return sum(c.hard for c in self.cards)    def soft_total(self ):        return sum(c.soft for c in self.cards)

This initialization sets all of the instance variables in a single step. The other methods are simply copies of the previous class definition. We can build aHand2 object in two ways. This first example loads one card at a time into aHand2 object:

d = Deck()P = Hand2( d.pop() )p.cards.append( d.pop() )p.cards.append( d.pop() )

This second example uses the*cards parameter to load a sequence ofCards class in a single step:

d = Deck()h = Hand2( d.pop(), d.pop(), d.pop() )

For unit testing, it's often helpful to build a composite object in a single statement in this way. More importantly, some of the serialization techniques from the next part will benefit from a way of building a composite object in a single, simple evaluation.

class GameStrategy:    def insurance( self, hand ):        return False    def split( self, hand ):        return False    def double( self, hand ):        return False    def hit( self, hand ):        return sum(c.hard for c in hand.cards) <= 17

dumb = GameStrategy()

• The player must place an initial bet based on the betting strategy.

• The player will then receive a hand.

• If the hand is splittable, the player must decide to split or not based on the play strategy. This can create additionalHand instances. In some casinos, the additional hands are also splittable.

• For eachHand instance, the player must decide to hit, double, or stand based on the play strategy.

• The player will then receive payouts, and they must update their betting strategy based on their wins and losses.

class Table:    def __init__( self ):        self.deck = Deck()    def place_bet( self, amount ):        print( "Bet", amount )    def get_hand( self ):        try:            self.hand= Hand2( d.pop(), d.pop(), d.pop() )            self.hole_card= d.pop()        except IndexError:            # Out of cards: need to shuffle.            self.deck= Deck()            return self.get_hand()        print( "Deal", self.hand )        return self.hand    def can_insure( self, hand ):        return hand.dealer_card.insure

class BettingStrategy:    def bet( self ):        raise NotImplementedError( "No bet method" )    def record_win( self ):        pass    def record_loss( self ):        passclass Flat(BettingStrategy):    def bet( self ):        return 1

import abcclass BettingStrategy2(metaclass=abc.ABCMeta):    @abstractmethod    def bet( self ):        return 1    def record_win( self ):        pass    def record_loss( self ):        pass

Tip

Avoid clone methods

A clone method that unnecessarily duplicates an object is rarely needed in Python. Using cloning may be an indication of failure to understand the object-oriented design principles available in Python.

A clone method encapsulates the knowledge of object creation in the wrong place. The source object that's being cloned cannot know about the structure of the target object that was built from the clone. However, the reverse (targets having knowledge about a source) is acceptable if the source provides a reasonably well-encapsulated interface.

class Hand3:    def __init__( self, *args, **kw ):        if len(args) == 1 and isinstance(args[0],Hand3):            # Clone an existing hand; often a bad idea            other= args[0]            self.dealer_card= other.dealer_card            self.cards= other.cards        else:            # Build a fresh, new hand.            dealer_card, *cards = args            self.dealer_card=  dealer_card            self.cards= list(cards)

h = Hand( deck.pop(), deck.pop(), deck.pop() )memento= Hand( h )

In order towrite a multi-strategy initialization, we're often forced to give up on specific named parameters. This design has the advantage that it is flexible, but the disadvantage that it has opaque, meaningless parameter names. It requires a great deal of documentation explaining the variant use cases.

We can expand our initialization to also split aHand object. The result of splitting aHand object is simply another constructor. The following code snippet shows how the splitting of aHand object might look:

class Hand4:    def __init__( self, *args, **kw ):        if len(args) == 1 and isinstance(args[0],Hand4):            # Clone an existing handl often a bad idea            other= args[0]            self.dealer_card= other.dealer_card            self.cards= other.cards        elif len(args) == 2 and isinstance(args[0],Hand4) and 'split' in kw:            # Split an existing hand            other, card= args            self.dealer_card= other.dealer_card            self.cards= [other.cards[kw['split']], card]        elif len(args) == 3:            # Build a fresh, new hand.            dealer_card, *cards = args            self.dealer_card=  dealer_card            self.cards= list(cards)        else:            raise TypeError( "Invalid constructor args={0!r} kw={1!r}".format(args, kw) )    def __str__( self ):        return ", ".join( map(str, self.cards) )

This design involves getting extra cards to build proper, split hands. When we create oneHand4 object from anotherHand4 object, we provide a split keyword argument that uses the index of theCard class from the originalHand4 object.

The following code snippet shows how we'd use this to split a hand:

d = Deck()h = Hand4( d.pop(), d.pop(), d.pop() )s1 = Hand4( h, d.pop(), split=0 )s2 = Hand4( h, d.pop(), split=1 )

We created an initialh instance ofHand4 and split it into two otherHand4 instances,s1 ands2, and dealt an additionalCard class into each. The rules of blackjack only allow this when the initial hand has two cards of equal rank.

While this__init__() method is rather complex, it has the advantage that it can parallel the way in whichfronzenset is created from an existing set. The disadvantage is that it needs a large docstring to explain all these variations.

When wehave multiple ways to create an object, it's sometimes more clear to use static methods to create and return instances rather than complex__init__() methods.

It's also possible to use class methods as alternate initializers, but there's little tangible advantage to receiving the class as an argument to the method. In the case of freezing or splitting aHand object, we might want to create two new static methods to freeze or split aHand object. Using static methods as surrogate constructors is a tiny syntax change in construction, but it has huge advantages when organizing the code.

The following is a version ofHand with static methods that can be used to build new instances ofHand from an existingHand instance:

class Hand5:    def __init__( self, dealer_card, *cards ):        self.dealer_card= dealer_card        self.cards = list(cards)    @staticmethod    def freeze( other ):        hand= Hand5( other.dealer_card, *other.cards )        return hand    @staticmethod    def split( other, card0, card1 ):        hand0= Hand5( other.dealer_card, other.cards[0], card0 )        hand1= Hand5( other.dealer_card, other.cards[1], card1 )        return hand0, hand1    def __str__( self ):        return ", ".join( map(str, self.cards) )

Onemethod freezes or creates amemento version. The other method splits aHand5 instance to create two new child instances ofHand5.

This is considerably more readable and preserves the use of the parameter names to explain the interface.

The following code snippet shows how we can split aHand5 instance with this version of the class:

d = Deck()h = Hand5( d.pop(), d.pop(), d.pop() )s1, s2 = Hand5.split( h, d.pop(), d.pop() )

We created an initialh instance ofHand5, split it into two other hands,s1 ands2, and dealt an additionalCard class into each. Thesplit() static method is much simpler than the equivalent functionality implemented via__init__(). However, it doesn't follow the pattern of creating afronzenset object from an existingsetobject.

class Player:    def __init__( self, table, bet_strategy, game_strategy ):        self.bet_strategy = bet_strategy        self.game_strategy = game_strategy        self.table= table    def game( self ):        self.table.place_bet( self.bet_strategy.bet() )        self.hand= self.table.get_hand()        if self.table.can_insure( self.hand ):            if self.game_strategy.insurance( self.hand ):                self.table.insure( self.bet_strategy.bet() )        # Yet more... Elided for now

table = Table()flat_bet = Flat()dumb = GameStrategy()p = Player( table, flat_bet, dumb )p.game()

class Player2:    def __init__( self, **kw ):        """Must provide table, bet_strategy, game_strategy."""        self.__dict__.update( kw )    def game( self ):        self.table.place_bet( self.bet_strategy.bet() )        self.hand= self.table.get_hand()        if self.table.can_insure( self.hand ):            if self.game_strategy.insurance( self.hand ):                self.table.insure( self.bet_strategy.bet() )        # etc.

p2 = Player2( table=table, bet_strategy=flat_bet, game_strategy=dumb )

>>> p1= Player2( table=table, bet_strategy=flat_bet, game_strategy=dumb)>>> p1.game()

>>> p2= Player2( table=table, bet_strategy=flat_bet, game_strategy=dumb, log_name="Flat/Dumb" )>>> p2.game()

class Player3( Player ):    def __init__( self, table, bet_strategy, game_strategy, **extras ):        self.bet_strategy = bet_strategy        self.game_strategy = game_strategy        self.table= table        self.__dict__.update( extras )

Type validation is rarely a sensible requirement. In a way, this might be a failure to fully understand Python. The notionalobjective is to validate that all of the arguments are of aproper type. The issue with trying to do this is that the definition ofproper is often far too narrow to be truly useful.

This is different from validating that objects meet other criteria. Numeric range checking, for example, may be essential to prevent infinite loops.

What can create problems is trying to do something like the following in an__init__() method:

class ValidPlayer:    def __init__( self, table, bet_strategy, game_strategy ):        assert isinstance( table, Table )        assert isinstance( bet_strategy, BettingStrategy )        assert isinstance( game_strategy, GameStrategy )        self.bet_strategy = bet_strategy        self.game_strategy = game_strategy        self.table= table

Theisinstance() method checks circumvent Python's normalduck typing.

Wewrite a casino game simulation in order to experiment with endless variations onGameStrategy. These are so simple (merely four methods) that there's little real benefit from inheritance from the superclass. We could define the classes independently, lacking an overall superclass.

The initialization error-checking shown in this example would force us to create subclasses merely to pass the error check. No usable code is inherited from the abstract superclass.

One of the biggest duck typing issues surrounds numeric types. Different numeric types will work in different contexts. Attempts to validate the types of arguments may prevent a perfectly sensible numeric type from working properly. When attempting validation, we have the following two choices in Python:

Notethat both are essentiallythe same. The code could perhaps break someday. It either breaks because a type was prevented from being used even though it's sensible or a type that's not really sensible was used.

The question is this: why restrict potential future use cases?

And the usual answer is that there's no good reason to restrict potential future use cases.

Rather than prevent a sensible, but possibly unforeseen, use case, we can provide documentation, testing, and debug logging to help other programmers understand any restrictions on the types that can be processed. We have to provide the documentation, logging, and test cases anyway, so there's minimal additional work involved.

The following is an example docstring that provides the expectations of the class:

class Player:    def __init__( self, table, bet_strategy, game_strategy ):        """Creates a new player associated with a table, and configured with proper betting and play strategies        :param table: an instance of :class:`Table`        :param bet_strategy: an instance of :class:`BettingStrategy`        :param  game_strategy: an instance of :class:`GameStrategy`        """        self.bet_strategy = bet_strategy        self.game_strategy = game_strategy        self.table= table

The programmer using this class has been warned about what the type restrictions are. The use of other types is permitted. If the type isn't compatible with the expected type, then things will break. Ideally, we'll use too likeunittest ordoctest to uncover the breakage.

The general Python policy regarding privacy can be summed up as follows:we're all adults here.

Object-oriented design makes an explicit distinction between interface and implementation. This is a consequence of the idea of encapsulation. A class encapsulates a data structure, an algorithm, an external interface, or something meaningful. The idea is to have the capsule separate the class-based interface from the implementation details.

However, noprogramming language reflects every design nuance. Python, typically, doesn't implement all design considerations as explicit code.

One aspect of a class design that is not fully carried into code is the distinction between theprivate (implementation) andpublic (interface) methods or attributes of an object. The notion of privacy in languages that support it (C++ or Java are two examples) is already quite complex. These languages include settings such as private, protected, and public as well as "not specified", which is a kind of semiprivate. The private keyword is often used incorrectly, making subclass definition needlessly difficult.

Python's notion of privacy is simple, as follows:

Names that begin with_ are honored as less public by some parts of Python. Thehelp() function generally ignores these methods. Tools such as Sphinx can conceal these names from documentation.

Python's internal names begin (and end) with__. This is how Python internals are kept from colliding with application features above the internals. The collection of these internal names is fully defined by the language reference. Further, there's no benefit to trying to use__ to attempt to create a "super private" attribute or method in our code. All that happens is that we create a potential future problem if a release of Python ever starts using a name we chose for internal purposes. Also, we're likely to run afoul of the internal name mangling that is applied to these names.

The rules for the visibility of Python names are as follows:

Generally, the Python approach is to register the intent of a method (or attribute) using documentationand a well-chosen name. Often, the interface methods will haveelaborate documentation, possibly includingdoctest examples, while the implementation methods will have more abbreviated documentation and may not havedoctest examples.

For programmers new to Python, it's sometimes surprising that privacy is not more widely used. For programmers experienced in Python, it's surprising how many brain calories get burned sorting out private and public declarations that aren't really very helpful because the intent is obvious from the method names and the documentation.