Fluent Python Clear, Concise, and Effective Programming pdf pdf

  Luciano Ramalho Fluent Python

  Fluent Python by Luciano Ramalho Copyright © 2014 Luciano Ramalho. All rights reserved.

  Printed in the United States of America. Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472.

O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are

also a). For more information, contact our corporate/

institutional sales departmen

  Meghan Blanchette and Rachel Roumeliotis FIX ME! Editors: Indexer:

  

FIX ME! Karen Montgomery

Production Editor: Cover Designer:

  FIX ME! David Futato Copyeditor: Interior Designer: Proofreader: FIX ME! Illustrator: Rebecca Demarest March 2015: First Edition Revision History for the First Edition: 2014-09-30: Early release revision 1 2014-12-05: Early release revision 2 2014-12-18: Early release revision 3 2015-01-27: Early release revision 4 2015-02-27: Early release revision 5 2015-04-15: Early release revision 6 2015-04-21: Early release revision 7

  

Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of O’Reilly

Media, Inc. !!FILL THIS IN!! and related trade dress are trademarks of O’Reilly Media, Inc.

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as

trademarks. Where those designations appear in this book, and O’Reilly Media, Inc. was aware of a trademark

claim, the designations have been printed in caps or initial caps.

While every precaution has been taken in the preparation of this book, the publisher and authors assume

no responsibility for errors or omissions, or for damages resulting from the use of the information contained

herein.

  ISBN: 978-1-491-94600-8 [?]

  Para Marta, com todo o meu amor.

  Table of Contents

  Part I.

  

1.

  4 8

  9 11 11 12

  12 14 14 15

  Part II.

  

2.

  20 21

  21 23 23 25

  26 26 27

  29 30 32

  33 33 34 35 36

  36 37

  38 42

  44 44 46

  47 48 51 52 54

  57 58

3. Dictionaries and sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

   66

  66 68

   71

  72 75 76 77 81

   85

  85 87

  90 93

  93 94

  

4.

  98 99

  102 103 105

  105 106 107 108 109

  110 113

  116 119 120 121

  124 126

  126 130

  132 133

  Part III.

  

5.

  140 141

  142 143 144 145 147

  148 150 154 156

  156 159

  161 162

  

6.

  168 168 172 175 176

  177 179 180

  

7.

  184 185 187 189 192 195 197

  198 200

  200 202

  205 206

  206 209

  211 212

  Part IV.

  

8.

  220 221

  223 224

  225 227

  229 230 234

  236 237 239

  240 242 243

  

9.

  248 248 252

  253 257 263 265

  267 268 270 271

10. Sequence hacking, hashing and slicing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

   278

  278 281 282

  283 285

  286 290 296 303 304

  

11.

  310 312 314 316 321 323

  323 324

  325 330 331 333

  336 339 340 341 343

  

12.

  350 353 358 360

  361

  361

  361

  361

  361

  362

  362 363 363

  364 368 369

  

13.

  374 374 377 382 386 390 394 395

  Part V.

  

14.

  404 406

  407 411

  413 414

  415 418 419 421 422

  425 426 435 436 438 439 441 442 442

  

  

15.

  450 452 456 457 461 461

  

16.

  466 466 470 471 473 477 479 485 491

  491 492

  500 502

  

17.

  507 509 511 513

  517 517 519 522

  527 529 532

   533

  

  

18.

   547

  548 550 554 556

  557 562

  564 566

  569

  570 575 578

   580

  Part VI.

  

19.

  588 590 593 594 596 600

  606 606 607

  609 610 612

  613 616 618

  618 618 619

  621 621

  

20.

  627 628 633 639

  642 644 645 646 647

  648

  650

  650

  650

  650

  651

  651 652 653 653

21. Class metaprogramming. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657

  658 661 663

  664 668

  670 674 676 678 679 680

  

  

A.

  Preface

Here’s the plan: when someone uses a feature you don’t understand, simply shoot them.

  

This is easier than learning something new, and before too long the only living coders

₁ will be writing in an easily understood, tiny subset of Python 0.9.6 <wink> .

  — Tim Peters legendary core developer and author of The Zen of Python

  “Python is an easy to learn, powerful programming language.” Those are the first words t is true, but there is a catch: because the language is easy to learn and put to use, many practicing Python programmers leverage only a fraction ot its powerful features.

  An experienced programmer may start writing useful Python code in a matter of hours. As the first productive hours become weeks and months, a lot of developers go on writing Python code with a very strong accent carried from languages learned before.

  Even if Python is your first language, often in academia and in introductory books it is presented while carefully avoiding language-specific features. As a teacher introducing Python to programmers experienced in other languages, I see another problem that this book tries to address: we only miss stuff we know about. Coming from another language, anyone may guess that Python supports regular ex‐ pressions, and look that up in the docs. But if you’ve never seen tuple unpacking or descriptors before, you will probably not search for them, and may end up not using those features just because they are specific to Python. This book is not an A-Z exhaustive reference of Python. My emphasis is in the language features that are either unique to Python or not found in many other popular languages. This is also mostly a book about the core language and some of its libraries. I will rarely talk about packages that are not in the standard library, even though the Python package index now lists more than 53.000 libraries and many of them are incredibly useful.

1. Message to comp.lang.python, Dec. 23, 2002: “Acrimony in c.l.p.”

  XXXtodo

  Who This Book Is For

  This book was written for practicing Python programmers who want to become pro‐ ficient in Python 3. If you know Python 2 but are willing to migrate to Python 3.4 or later, you should be fine. At this writing the majority of professional Python program‐ mers are using Python 2, so I took special care to highlight Python 3 features that may be new to that audience. However, Fluent Python is about making the most of Python 3.4, and I do not spell out the fixes needed to make the code work in earlier versions. Most examples should run in Python 2.7 with little or no changes, but in some cases backporting would require significant rewriting.

  Having said that, I believe this book may be useful even if you must stick with Python 2.7, because the core concepts are still the same. Python 3 is not a new language, and is a good starting point. Of course, there have been changes after Python 3.0 was released in 2009, but none as important as those in 3.0.

  If you are not sure whether you know enough Python to follow along, review the topics of the official opics covered in the tutorial will not be explained here, except for some features that are new in Python 3.

  Who This Book Is Not For

  If you are just learning Python, this book is going to be hard to follow. Not only that, if you read it too early in your Python journey, it may give you the impression that every Python script should leverage special methods and metaprogramming tricks. Premature abstraction is as bad as premature optimization.

  How This Book is Organized

  The core audience for this book should not have trouble jumping directly to any chapter in this book. However, I did put some thought into their ordering. I tried to emphasize using what is available before discussing how to build your own. For exam

Chapter 2 in Part II covers sequence types that are ready to use, including

  some that don’t get a lot of attention, like collections.deque. Building user-defined sequences is only addressed in Part IV, where we also see how to leverage the Abstract Base Classes (ABC) from collections.abc. Creating your own ABCs is discussed even later in Part IV, because I believe it’s important to be comfortable using an ABC before writing your own.

  This approach has a few advantages. First, knowing what is ready to use can save you from reinventing the wheel. We use existing collection classes more often than we im‐ plement our own, and we can give more attention to the advanced usage of available tools by deferring the discussion on how to create new ones. We are also more likely to inherit from existing ABCs than to create a new ABC from scratch. And finally, I believe it is easier to understand the abstractions after you’ve seen them in action.

  The downside of this strategy are the forward references scattered throughout the chapters. I hope these will be easier to tolerate now that you know why I chose this path. The chapters are split in 6 parts. This is the idea behind each of them:

  Part I: Prologue A single chapter about the Python Data Model explaining how the special methods

  (e.g. __repr__) are the key to the consistent behavior of objects of all types — in a language that is admired for its consistency. Understanding various facets of the data model is the subject of most of the rest of the book, but

Chapter 1 provides a high-level overview. Part II: Data structures The chapters in this part cover the use of collection types: sequences, mappings and

  sets, as well as the str versus bytes split — the reason for much joy for Python 3 users and much pain for Python 2 users who have not yet migrated their code bases. The main goals are to recall what is already available and to explain some behavior that is sometimes surprising, like the reordering of dict keys when we are not looking, or the caveats of locale-dependent Unicode string sorting. To achieve these goals, the coverage is sometimes high level and wide — when many variations of sequences and mappings are presented — and sometimes deep, for example when we dive into the hash tables underneath the dict and set types.

  Part III: Functions as objects Here we talk about functions as first-class objects in the language: what that means,

  how it affects some popular design patterns, and how to implement function dec‐ orators by leveraging closures. Also covered here is the general concept of callables in Python, function attributes, introspection, parameter annotations, and the new nonlocal declaration in Python 3.

  Part IV: Object Oriented Idioms Now the focus is on building classes. In part II the class declaration appears in few

  examples; part IV presents many classes. Like any OO language, Python has its particular set of features that may or may not be present in the language where you and I learned class-based programming. The chapters explain how references work, what mutability really means, the lifecycle of instances, how to build your own collections and ABCs, how to cope with multiple inheritance and how to implement operator overloading — when that makes sense.

  Part V: Control flow Covered in this part are the language constructs and libraries that go beyond se‐

  quential control flow with conditionals, loops and subroutines. We start with gen‐ erators, then visit context managers and coroutines, including the challenging but powerful new yield from syntax. Part V closes with high level a introduction to modern concurrency in Python with collections.futures — using threads and processes under the covers with the help of futures — and doing event-oriented I/ O with asyncio — leveraging futures on top of coroutines and yield from.

  Part VI: Metaprogramming This part starts with a review of techniques for building classes with attributes

  created dynamically to handle semi-structured data such as JSON datasets. Next we cover the familiar properties mechanism, before diving into how object attribute access works at a lower level in Python using descriptors. The relationship between functions, methods and descriptors is explained. Throughout Part VI, the step by step implementation of a field validation library uncovers subtle issues the lead to the use of the advanced tools of the last chapter: class decorators and metaclasses.

  Hands-on Approach

  Often we’ll use the interactive Python console to explore the language and libraries. I feel it is important to emphasize the power of this learning tool, particularly for those readers who’ve had more experience with static, compiled languages that don’t provide a REPL — read-eval-print-loop.

  

  One of the standard Python testing packages, ulating console sessions and verifying that the expressions evaluate to the responses shown. I used doctest to check most of the code in this book, including the console listings. You don’t need to use or even know about doctest to follow along: the key feature of doctests is that they look like transcripts of interactive Python console sessions, so you can easily try out the demonstrations yourself. Sometimes I will explain what we want to accomplish by showing a doctest before the code that makes it pass. Firmly establishing what is to be done before thinking about how to do it helps focus our coding effort. Writing tests first is the basis of TDD (Test Driven Development) and I’ve also found it helpful when teaching. If you are unfamiliar

  

  You’ll find that you can verify the correctness of most of the code in the book by typing python3 -m doctest example_script.py in the command shell of your OS.

  Hardware used for timings

  The book has some simple benchmarks and timings. Those tests were performed on one or the other laptop I used to write the book: a 2011 MacBook Pro 13” with a 2.7 GHz Intel Core i7 CPU, 8MB of RAM and a spinning hard disk, and a 2014 MacBook Air 13” with a 1.4 GHZ Intel Core i5 CPU, 4MB of RAM and a solid state disk. The MacBook Air has a slower CPU and less RAM, but its RAM is faster (1600 vs. 1333 MHz) and the SSD is much faster than the HD. In daily usage I can’t tell which machine is faster.

  Soapbox: my personal perspective

  I have been using, teaching and debating Python since 1998, and I enjoy studying and comparing programming languages, their design and the theory behind them. At the end of some chapters I have added a section called Soapbox with my own perspective about Python and other languages. Feel free to skip that if you are not into such dis‐ cussions. Their content is completely optional.

  Python Jargon I wanted this to be a book not only about Python but also about the culture around it.

  Over more than 20 years of communications, the Python community has developed its own particular lingo and acronyms. The collects terms that have special meaning among Pythonistas.

  Python version covered

  I tested all the code in the book using Python 3.4 — that is, CPython 3.4, i.e. the most popular Python implementation written in C. There is only one excpetion: the sidebar

  

shows the @ operator which is only

supported by Python 3.5.

  Almost all code in the book should work with any Python 3.x compatible interpreter, including PyPy3 2.4.0 which is compatible with Python 3.2.5. A notable exception are the examples using yield from and asyncio, which are only available in Python 3.3 or later.

  Most code should also work with Python 2.7 with minor changes, except the Unicode- related exam

Chapter 4 , and the exceptions already noted for Python 3 versions earlier than 3.3.

  Conventions Used in This Book

  XXXrevise The following typographical conventions are used in this book:

  Italic Indicates new terms, URLs, email addresses, filenames, and file extensions.

  Constant width Used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords. Note that when a line break falls within a con stant_width term, a hyphen is not added — it could be misunderstood as part of the term.

  Constant width bold Shows commands or other text that should be typed literally by the user.

  Constant width italic

  Shows text that should be replaced with user-supplied values or by values deter‐ mined by context.

  «Guillemets»

  Indicate that the enclosed parameter is optional, eg.: dir(«object») ² This element signifies a tip or suggestion.

  This element signifies a general note.

  This element indicates a warning or caution.

2. In the Python docs, square brackets are used for this purpose, but I have seen people confuse them with list displays.

  Using Code Examples

  Every script and most code snippets that appear in the book are a

  y on Github.

  Supplemental material (code examples, exercises, etc.) is available for download at

  

  This book is here to help you get your job done. In general, if example code is offered with this book, you may use it in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of ex‐ ample code from this book into your product’s documentation does require permission. We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Book Title by Some Author (O’Reilly). Copyright 2012 Some Copyright Holder, 978-0-596-xxxx-x.” If you feel your use of code examples falls outside fair use or the permission given above,

  

  Safari® Books Online

   in both book and video form from the world’s leading authors in technology and business. Technology professionals, software developers, web designers, and business and crea‐ tive professionals use Safari Books Online as their primary resource for research, prob‐ lem solving, learning, and certification training. Safari B

  

ve access to thousands of

  books, training videos, and prepublication manuscripts in one fully searchable database from publishers like O’Reilly Media, Prentice Hall Professional, Addison-Wesley Pro‐ fessional, Microsoft Press, Sams, Que, Peachpit Press, Focal Press, Cisco Press, John Wiley & Sons, Syngress, Morgan Kaufmann, IBM Redbooks, Packt, Adobe Press, FT Press, Apress, Manning, New Riders, McGraw-Hill, Jones & Bartlett, Course Technol‐ ogyor more information about Safari Books Online, please visit us

  

  How to Contact Us

  Please address comments and questions concerning this book to the publisher: O’Reilly Media, Inc.

  1005 Gravenstein Highway North Sebastopol, CA 95472 800-998-9938 (in the United States or Canada) 707-829-0515 (international or local) 707-829-0104 (fax)

  We have a web page for this book, where we list errata, examples, and any additional

  

  To comment or ask technical questions about this book, send email to

   .

  For more information about our books, courses, conferences, and news, see our website at .

  

  Find us on F Follow us on Twitter:

  

  Watch us on YouT

  Acknowledgments

  The Bauhaus chess set by Josef Hartwig is an example of excellent design: beautiful, simple and clear. Guido van Rossum, son of an architect and brother of a master font designer, created a masterpiece of language design. I love teaching Python because it is beautiful, simple and clear.

  Alex Martelli and Anna Ravenscroft were the first people to see the outline of this book and encouraged me to submit it to O’Reilly for publication. Their books taught me idiomatic Python and are models of clarity, accuracy and depth in technical writing.

  

verflow are a fountain of insights about the language

and its proper use.

  Martelli and Ravescroft were also technical reviewers of this book, along with Lennart Regebro and Leonardo Rochael. Everyone in this outstanding technical review team has at least 15 years Python experience, with many contributions to high-impact Python projects in close contact with other developers in the community. Together they sent me hundreds of corrections, suggestions, questions and opinions, adding tremendous value to the book. Victor Stinner kindly reviewed

Chapter 18 , bringing his expertise as

  an asyncio maintainer to the technical review team. It was a great privilege and a pleas‐ ure to collaborate with them over these last several months. Editor Meghan Blanchette was an outstanding mentor, helping me improve the orga‐ nization and flow of the book, letting me know when it was boring, and keeping me from delaying even more. Brian MacDonald edited chapters in

  while Meghan

  was away. I enjoyed working with him, and with everyone I’ve contacted at O’Reilly, including the Atlas development and support team (Atlas is the O’Reilly book publishing platform which I was fortunate to use to write this book). Mario Domenech Goulart provided numerous, detailed suggestions starting with the first Early Release. I also received valuable feedback from Dave Pawson, Elias Dorneles, Leonardo Alexandre Ferreira Leite, Bruce Eckel, J. S. Bueno, Rafael Gonçalves, Alex Chiaranda, Guto Maia, Lucas Vido and Lucas Brunialti.

  Over the years, a number of people urged me to become an author, but the most per‐ suasive were Rubens Prates, Aurelio Jargas, Rudá Moura and Rubens Altimari. Mauricio Bussab opened many doors for me, including my first real shot at writing a book. Renzo Nuccitelli supported this writing project all the way, even if that meant a slow start for

  

  The wonderful Brazilian Python community is knowledgeable, giving and fun. The python-brasil group has thousands of people and our national conferences bring to‐ gether hundreds, but the most influential in my journey as a Pythonista were Leonardo Rochael, Adriano Petrich, Daniel Vainsencher, Rodrigo RBP Pimentel, Bruno Gola, Leonardo Santagada, Jean Ferri, Rodrigo Senra, J. S. Bueno, David Kwast, Luiz Irber, Osvaldo Santana, Fernando Masanori, Henrique Bastos, Gustavo Niemayer, Pedro Werneck, Gustavo Barbieri, Lalo Martins, Danilo Bellini and Pedro Kroger.

  Dorneles Tremea was a great friend — incredibly generous with his time and knowl‐ edge — an amazing hacker and the most inspiring leader of the Brazilian Python As‐ sociation. He left us too early. My students over the years taught me a lot through their questions, insights, feedback and creative solutions to problems. Erico Andrei and Simples Consultoria made it pos‐ sible for me to focus on being a Python teacher for the first time. Martijn Faassen was my Grok mentor and shared invaluable insights with me about Python and Neanderthals. His work and that of Paul Everitt, Chris McDonough, Tres Seaver, Jim Fulton, Shane Hathaway, Lennart Regebro, Alan Runyan, Alexander Limi, Martijn Pieters, Godefroid Chapelle and others from the Zope, Plone and Pyramid planets have been decisive in my career. Thanks to Zope and surfing the first Web wave, I was able to start making a living with Python in 1998. José Octavio Castro Neves was my partner in the first Python-centric software house in Brazil.

  I have too many gurus in the wider Python community to list them all, but besides those already mentioned, I am indebted to Steve Holden, Raymond Hettinger, A.M. Kuchling, David Beazley, Fredrik Lundh, Doug Hellmann, Nick Coghlan, Mark Pilgrim, Martijn Pieters, Bruce Eckel, Michele Simionato, Wesley Chun, Brandon Craig Rhodes, Philip Guo, Daniel Greenfeld, Audrey Roy and Brett Slatkin for teaching me new and better ways to teach Python.

  Most of these pages were written in my home office and in two labs: CoffeeLab and Garoa Hacker Clube. ila Madalena, São Paulo, Brazil. is a hackerspace open to all: a community lab where anyone can freely try out new ideas.

  The Garoa community provided inspiration, infrastructure and slack. I think Aleph would enjoy this book. My mother Maria Lucia and my father Jairo always supported me in every way. I wish he was here to see the book; I am glad I can share it with her. My wife Marta Mello endured 15 months of a husband who was always working, but remained supportive and coached me through some critical moments in the project when I feared I might drop out of the marathon. Thank you all, for everything.

  PART I Prologue

CHAPTER 1 The Python Data Model Guido’s sense of the aesthetics of language design is amazing. I’ve met many fine language

  

designers who could build theoretically beautiful languages that no one would ever use,

but Guido is one of those rare people who can build a language that is just slightly less

₁ theoretically beautiful but thereby is a joy to write programs in .

  — Jim Hugunin creator of Jython, co-creator of AspectJ, architect of the .Net DLR

  One of the best qualities of Python is its consistency. After working with Python for a while, you are able to start making informed, correct guesses about features that are new to you. However, if you learned another object oriented language before Python, you may have found it strange to spell len(collection) instead of collection.len(). This apparent oddity is the tip of an iceberg which, when properly understood, is the key to everything we call Pythonic. The iceberg is called the Python Data Model, and it describes the API that you can use to make your own objects play well with the most idiomatic language features.

  You can think of the Data Model as a description of Python as a framework. It formalizes the interfaces of the building blocks of the language itself, such as sequences, iterators, functions, classes, context managers and so on. While coding with any framework, you spend a lot of time implementing methods that are called by the framework. The same happens when you leverage the Python Data Model. The Python interpreter invokes special methods to perform basic object oper‐ ations, often triggered by special syntax. The special method names are always spelled with leading and trailing double underscores, i.e. __getitem__. For example, the syntax

1. Story of Jython , written as a foreword to Jython Essentials (O’Reilly, 2002), by Samuele Pedroni and Noel Rappin.

• iteration;
• collections;
• attribute access;
• operator overloading;
• function and method invocation;
• object creation and destruction;
• string representation and formatting;
• managed contexts (i.e. with blocks);

  

3. I personally first heard “dunder” from Steve Holden. The English language Wikipedia Mark John‐

son and Tim Hochberg for the first written records of “dunder” in responses to the question “How do you pronounce __ (double underscore)?” in the python-list in September 26, 2002:

  obj[key] is supported by the __getitem__ special method. To evaluate my_collec tion[key] , the interpreter calls my_collection.__getitem__(key).

  The special method names allow your objects to implement, support and interact with basic language constructs such as:

  Magic and dunder The term magic method is slang for special method, but when talk‐ ing about a specific method like __getitem__, some Python devel‐ opers take the shortcut of saying “under-under-getitem” which is

ambiguous, since the syntax __x has another special meaning

² . But being precise and pronouncing “under-under-getitem-under- under” is tiresome, so I follow the lead of author and teacher Steve Holden and say “dunder-getitem”. All experienced Pythonistas un‐ derstand that shortcut. As a result, the special methods are also known as dunder methods ³ .

  A Pythonic Card Deck

  The following is a very simple example, but it demonstrates the power of implementing just two special methods, __getitem__ and __len__.

  t a deck of playing cards:

2. See “Private and “protected” attributes in Python” on page 263

  Example 1-1. A deck as a sequence of cards. import collections Card = collections . namedtuple ( 'Card' , [ 'rank' , 'suit' ]) class FrenchDeck : ranks = [ str ( n ) for n in range ( 2 , 11 )] + list ( 'JQKA' ) suits = 'spades diamonds clubs hearts' . split () def __init__ ( self ): self . _cards = [ Card ( rank , suit ) for suit in self . suits for rank in self . ranks ] def __len__ ( self ): return len ( self . _cards ) def __getitem__ ( self , position ): return self . _cards [ position ]

  The first thing to note is the use of collections.namedtuple to construct a simple class to represent individual cards. Since Python 2.6, namedtuple can be used to build classes of objects that are just bundles of attributes with no custom methods, like a database record. In the example we use it to provide a nice representation for the cards in the deck, as shown in the console session:

  >>> beer_card = Card ( '7' , 'diamonds' ) >>> beer_card Card(rank='7', suit='diamonds') But the point of this example is the FrenchDeck class. It’s short, but it packs a punch.

  First, like any standard Python collection, a deck responds to the len() function by returning the number of cards in it.

  >>> deck = FrenchDeck ()

  >>> len ( deck )

52 Reading specific cards from the deck, say, the first or the last, should be as easy as deck[0] or deck[-1], and this is what the __getitem__ method provides.

  >>> deck [ ]

  Card(rank='2', suit='spades') >>> deck [ - 1 ] Card(rank='A', suit='hearts')

  Should we create a method to pick a random card? No need. Python already has a function to get a random item from a sequence: random.choice. We can just use it on a deck instance:

  >>> from random import choice >>> choice ( deck )

  Card(rank='3', suit='hearts') >>> choice ( deck ) Card(rank='K', suit='spades') >>> choice ( deck ) Card(rank='2', suit='clubs')

  We’ve just seen two advantages of using special methods to leverage the Python Data Model:

  1. The users of your classes don’t have to memorize arbitrary method names for stan‐ dard operations (“How to get the number of items? Is it .size() .length() or what?”)

  2. It’s easier to benefit from the rich Python standard library and avoid reinventing the wheel, like the random.choice function. But it gets better. Because our __getitem__ delegates to the [] operator of self._cards, our deck auto‐ matically supports slicing. Here’s how we look at the top three cards from a brand new deck, and then pick just the aces by starting on index 12 and skipping 13 cards at a time:

  >>> deck [: 3 ] [Card(rank='2', suit='spades'), Card(rank='3', suit='spades'), Card(rank='4', suit='spades')] >>> deck [ 12 :: 13 ]

  [Card(rank='A', suit='spades'), Card(rank='A', suit='diamonds'), Card(rank='A', suit='clubs'), Card(rank='A', suit='hearts')]

  Just by implementing the __getitem__ special method, our deck is also iterable:

  >>> for in # doctest: +ELLIPSIS card deck :

  ... print ( card ) Card(rank='2', suit='spades')

  Card(rank='3', suit='spades') Card(rank='4', suit='spades') ...

  The deck can also be iterated in reverse:

  >>> for card in reversed ( deck ): # doctest: +ELLIPSIS ... print ( card ) Card(rank='A', suit='hearts')

  Card(rank='K', suit='hearts') Card(rank='Q', suit='hearts') ...

  Ellipsis in doctests Whenever possible, the Python console listings in this book were extracted from doctests to insure accuracy. When the output was too long, the elided part is marked by an ellipsis ... like in the last line above. In such cases, we used the # doctest: +ELLIPSIS directive to make the doctest pass. If you are trying these examples in the inter‐

active console, you may omit the doctest directives altogether.

  Iteration is often implicit. If a collection has no __contains__ method, the in operator does a sequential scan. Case in point: in works with our FrenchDeck class because it is iterable. Check it out:

  >>> Card ( 'Q' , 'hearts' ) in deck True >>>

  Card ( '7' , 'beasts' ) in deck

  False

  How about sorting? A common system of ranking cards is by rank (with aces being highest), then by suit in the order: spades (highest), then hearts, diamonds and clubs (lowest). Here is a function that ranks cards by that rule, returning 0 for the 2 of clubs and 51 for the ace of spades:

  suit_values = dict ( spades = 3 , hearts = 2 , diamonds = 1 , clubs = ) def spades_high ( card ): rank_value = FrenchDeck . ranks . index ( card . rank ) return rank_value * len ( suit_values ) + suit_values [ card . suit ]

  Given spades_high, we can now list our deck in order of increasing rank:

  >>> for card in sorted ( deck , key = spades_high ): # doctest: +ELLIPSIS ... print ( card ) Card(rank='2', suit='clubs') Card(rank='2', suit='diamonds') Card(rank='2', suit='hearts') ... ( 46 cards ommitted ) Card(rank='A', suit='diamonds') Card(rank='A', suit='hearts') Card(rank='A', suit='spades')

  Although FrenchDeck implicitly inherits from object ⁴ , its functionality is not inherited, but comes from leveraging the Data Model and composition. By implementing the special methods __len__ and __getitem__ our FrenchDeck behaves like a standard Python sequence, allowing it to benefit from core language features — like iteration and slicing — and from the standard library, as shown by the examples using ran

4. In Python 2 you’d have to be explicit and write FrenchDeck(object), but that’s the default in Python 3.

  dom.choice , reversed and sorted. Thanks to composition, the __len__ and __geti tem__ implementations can hand off all the work to a list object, self._cards.

  How about shuffling? As implemented so far, a FrenchDeck cannot be shuffled, because it is immutable: the cards and their positions cannot be changed, ex‐ cept by violating encapsulation and handling the _cards attribute directly. In

Chapter 11 that will be fixed by adding a one-line __seti

  tem__ method.

  How special methods are used

  The first thing to know about special methods is that they are meant to be called by the Python interpreter, and not by you. You don’t write my_object.__len__(). You write len(my_object) and, if my_object is an instance of a user defined class, then Python calls the __len__ instance method you implemented.

  But for built-in types like list, str, bytearray etc., the interpreter takes a shortcut: the CPython implementation of len() actually returns the value of the ob_size field in the PyVarObject

  C struct that represents any variable-sized built-in object in memory. This is much faster than calling a method. More often than not, the special method call is implicit. For example, the statement for i in x: actually causes the invocation of iter(x) which in turn may call x.__iter__() if that is available. Normally, your code should not have many direct calls to special methods. Unless you are doing a lot of metaprogramming, you should be implementing special methods more often than invoking them explicitly. The only special method that is frequently called by user code directly is __init__, to invoke the initializer of the superclass in your own __init__ implementation. If you need to invoke a special method, it is usually better to call the related built-in function, such as len, iter, str etc. These built-ins call the corresponding special method, but often provide other services and — for built-in types — are faster than method calls. See for example

   .

  Avoid creating arbitrary, custom attributes with the __foo__ syntax because such names may acquire special meanings in the future, even if they are unused today.

  Emulating numeric types

  Several special methods allow user objects to respond to operators such as +. We will cover tha

   ).

Figure 1-1. Example of 2D vector addition. Vector(2, 4) + Vector(2, 1) results in

Vector(4, 5). The built-in complex type can be used to represent 2D vectors, but our class can be extended to represent n-dimensional vectors. We will do that in

Chapter 14 . We will start by designing the API for such a class by writing a simulated console session

  which we can use later as doctest. The following snippet tests the vector addition pic‐ :

  >>> v1 = Vector ( 2 , 4 ) >>> v2 = Vector ( 2 , 1 )

  v1 v2 Vector(4, 5)

• >>>

  Note how the + operator produces a Vector result which is displayed in a friendly man‐ ner in the console.

  The abs built-in function returns the absolute value of integers and floats, and the magnitude of complex numbers, so to be consistent our API also uses abs to calculate the magnitude of a vector:

  >>> v = Vector ( 3 , 4 ) >>> abs ( v )

5.0 We can also implement the * operator to perform scalar multiplication, i.e. multiplying

  a vector by a number to produce a new vector with the same direction and a multiplied magnitude:

• >>> v

3 Vector(9, 12)

• >>> abs ( v 3 )

15.0 Example 1-2 is a Vector class implementing the operations just described, through the

  use of the special methods __repr__, __abs__, __add__ and __mul__: Example 1-2. A simple 2D vector class.

  from math import hypot class Vector : def

  __init__ ( self , x = , y = ): self . x = x self . y = y def __repr__ ( self ): return

  'Vector(%r, %r)' % ( self . x , self . y ) def __abs__ ( self ): return hypot ( self . x , self . y ) def

  __bool__ ( self ): return bool ( abs ( self )) def __add__ ( self , other ):

• x = self . x other . x

  y + = self . y other . y return

  Vector ( x , y ) def __mul__ ( self , scalar ):

• * return Vector ( self . x scalar , self * . y scalar )

  Note that although we implemented four special methods (apart from __init__), none of them is directly called within the class or in the typical usage of the class illustrated by the console listings. As mentioned before, the Python interpreter is the only frequent caller of most special methods. In the next sections we discuss the code for each special method.

  String representation

  The __repr__ special method is called by the repr built-in to get string representation of the object for inspection. If we did not implement __repr__, vector instances would be shown in the console like <Vector object at 0x10e100070>. The interactive console and debugger call repr on the results of the expressions evalu‐ ated, as does the '%r' place holder in classic formatting with % operator, and the !r ₅ con used in the str.format method .

  Note that in our __repr__ implementation we used %r to obtain the standard repre‐ sentation of the attributes to be displayed. This is good practice, as it shows the crucial difference between Vector(1, 2) and Vector('1', '2') — the latter would not work in the context of this example, because the constructors arguments must be numbers, not str. The string returned by __repr__ should be unambiguous and, if possible, match the source code necessary to recreate the object being represented. That is why our chosen representation looks like calling the constructor of the class, e.g. Vector(3, 4). Contrast __repr__ with with __str__, which is called by the str() constructor and implicitly used by the print function. __str__ should return a string suitable for display to end-users. If you only implement one of these special methods, choose __repr__, because when no custom __str__ is available, Python will call __repr__ as a fallback.

   is a StackOverflow question with excellent contributions from

Pythonistas Alex Martelli and Martijn Pieters.

  Arithmetic operators

implements two operators: + and *, to show basic usage of __add__ and

  __mul__ . Note that in both cases, the methods create and return a new instance of

  

5. Speaking of the % operator and the str.format method, the reader will notice I use both in this book, as does the Python community at large. I am increasingly favoring the more powerful str.format, but I am aware many Pythonistas prefer the simpler %, so we’ll probably see both in Python source code for the foreseeable future. Vector , and do not modify either operand — self or other are merely read. This is the expected behavior of infix operators: to create new objects and not touch their operands.

  I will have a lot more to say about tha

  As implemented, allows multiplying a Vector by a number, but not a number by a Vector, which violates the commu‐ tative property of multiplication. We will fix that with the special method __rmul__ in