Fluent Python Luciano Ramalho install download

https://ebookmeta.com/product/fluent-python-luciano-ramalho/

Download more ebook from https://ebookmeta.com

Fluent Python

Luciano Ramalho

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 available for most titles (
http://safaribooksonline.com). For more information, contact our
corporate/

institutional sales department: 800-998-9938 or

corporate@oreilly.com.

Editors: Meghan Blanchette and Rachel Roumeliotis

Indexer: FIX ME!

Production Editor: FIX ME!

Cover Designer: Karen Montgomery

Copyeditor: FIX ME!

Interior Designer: David Futato

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

See http://oreilly.com/catalog/errata.csp?isbn=9781491946008 for

release details.

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

Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . xv

Part I. Prologue

1. The Python Data Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

.........................3

A Pythonic Card Deck 4

How special methods are used 8

Emulating numeric types 9

String representation 11

Arithmetic operators 11

Boolean value of a custom type 12

Overview of special methods 12

Why len is not a method 14

Chapter summary 14

Further reading 15

Part II. Data structures

2. An array of sequences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . 19

Overview of built-in sequences 20

List comprehensions and generator expressions 21

List comprehensions and readability 21

Listcomps versus map and filter 23

Cartesian products 23

Generator expressions 25

Tuples are not just immutable lists 26

Tuples as records 26

Tuple unpacking 27

Nested tuple unpacking 29

Named tuples 30

Tuples as immutable lists 32

Slicing 33

Why slices and range exclude the last item 33

Slice objects 34

Multi-dimensional slicing and ellipsis 35

Assigning to slices 36
Using + and * with sequences 36

Building lists of lists 37

Augmented assignment with sequences 38

A += assignment puzzler 40

list.sort and the sorted built-in function 42

Managing ordered sequences with bisect 44

Searching with bisect 44

Inserting with bisect.insort 46

When a list is not the answer 47

Arrays 48

Memory views 51

NumPy and SciPy 52

Deques and other queues 54

Chapter summary 57

Further reading 58

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

. . . . . . . . . . . . . . . . . . . . . . . . 63

Generic mapping types 64

dict comprehensions 66

Overview of common mapping methods 66

Handling missing keys with setdefault 68

Mappings with flexible key lookup 70

defaultdict: another take on missing keys 71

The __missing__ method 72

Variations of dict 75

Subclassing UserDict. 76

Immutable mappings 77

Set theory 79

set literals 80

set comprehensions 81

Set operations 82

dict and set under the hood 85

A performance experiment 85

Hash tables in dictionaries 87

vi | Table of Contents

Practical consequences of how dict works 90

How sets work — practical consequences 93

Chapter summary 93

Further reading 94
4. Text versus bytes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . 97

Character issues 98

Byte essentials 99

Structs and memory views 102

Basic encoders/decoders 103

Understanding encode/decode problems 105

Coping with UnicodeEncodeError 105

Coping with UnicodeDecodeError 106

SyntaxError when loading modules with unexpected encoding 107

How to discover the encoding of a byte sequence 108

BOM: a useful gremlin 109

Handling text files 110

Encoding defaults: a madhouse 113

Normalizing Unicode for saner comparisons 116

Case folding 119

Utility functions for normalized text matching 120

Extreme “normalization”: taking out diacritics 121

Sorting Unicode text 124

Sorting with the Unicode Collation Algorithm 126

The Unicode database 126

Dual mode str and bytes APIs 128

str versus bytes in regular expressions 129

str versus bytes on os functions 130

Chapter summary 132

Further reading 133

Part III. Functions as objects

5. First-class functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . 139

Treating a function like an object 140

Higher-order functions 141

Modern replacements for map, filter and reduce 142

Anonymous functions 143

The seven flavors of callable objects 144

User defined callable types 145

Function introspection 147

Table of Contents | vii

From positional to keyword-only parameters 148

Retrieving information about parameters 150

Function annotations 154

Packages for functional programming 156

The operator module 156

Freezing arguments with functools.partial 159

Chapter summary 161

Further reading 162

6. Design patterns with first-class functions. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . 167

Case study: refactoring Strategy 168

Classic Strategy 168

Function-oriented Strategy 172

Choosing the best strategy: simple approach 175

Finding strategies in a module 176

Command 177

Chapter summary 179

Further reading 180

7. Function decorators and closures. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . 183

Decorators 101 184

When Python executes decorators 185

Decorator-enhanced Strategy pattern 187

Variable scope rules 189

Closures 192

The nonlocal declaration 195

Implementing a simple decorator 197

How it works 198

Decorators in the standard library 200

Memoization with functools.lru_cache 200

Generic functions with single dispatch 202

Stacked decorators 205

Parametrized Decorators 206

A parametrized registration decorator 206

The parametrized clock decorator 209

Chapter summary 211

Further reading 212

viii | Table of Contents

Part IV. Object Oriented Idioms

8. Object references, mutability and recycling. . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . 219

Variables are not boxes 220

Identity, equality and aliases 221

Choosing between == and is 223

The relative immutability of tuples 224

Copies are shallow by default 225

Deep and shallow copies of arbitrary objects 227

Function parameters as references 229

Mutable types as parameter defaults: bad idea 230

Defensive programming with mutable parameters 232

del and garbage collection 234

Weak references 236

The WeakValueDictionary skit 237

Limitations of weak references 239

Tricks Python plays with immutables 240

Chapter summary 242

Further reading 243

9. A Pythonic object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . 247

Object representations 248

Vector class redux 248

An alternative constructor 251

classmethod versus staticmethod 252

Formatted displays 253

A hashable Vector2d 257

Private and “protected” attributes in Python 263

Saving space with the __slots__ class attribute 265

The problems with __slots__ 267

Overriding class attributes 268

Chapter summary 270

Further reading 271

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

. . . . . . . . . . . . . . . . . . . . . . . 277

Vector: a user-defined sequence type 278

Vector take #1: Vector2d compatible 278

Protocols and duck typing 281

Vector take #2: a sliceable sequence 282

How slicing works 283

A slice-aware __getitem__ 285

Table of Contents | ix

Vector take #3: dynamic attribute access 286

Vector take #4: hashing and a faster == 290

Vector take #5: formatting 296

Chapter summary 303

Further reading 304

11. Interfaces: from protocols to ABCs. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . 309

Interfaces and protocols in Python culture 310

Python digs sequences 312

Monkey-patching to implement a protocol at run time 314

Waterfowl and ABCs 316

Subclassing an ABC 321

ABCs in the standard library. 323

ABCs in collections.abc 323

The numbers tower of ABCs 324

Defining and using an ABC 325

ABC syntax details 330

Subclassing the Tombola ABC 331

A virtual subclass of Tombola 333

How the Tombola subclasses were tested 336

Usage of register in practice 339

Geese can behave as ducks 340

Chapter summary 341

Further reading 343

12. Inheritance: for good or for worse. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . 349

Subclassing built-in types is tricky 350

Multiple inheritance and method resolution order 353

Multiple inheritance in the real world 358

Coping with multiple inheritance 360

1. Distinguish interface inheritance from implementation inheritance

361

2. Make interfaces explicit with ABCs 361

3. Use mixins for code reuse 361

4. Make mixins explicit by naming 361

5. An ABC may also be a mixin; the reverse is not true 361

6. Don’t subclass from more than one concrete class 362

7. Provide aggregate classes to users 362

8. “Favor object composition over class inheritance.” 363

Tkinter: the good, the bad and the ugly 363

A modern example: mixins in Django generic views 364

Chapter summary 368

Further reading 369

x | Table of Contents
13. Operator overloading: doing it right. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . 373

Operator overloading 101 374

Unary operators 374

Overloading + for vector addition 377

Overloading * for scalar multiplication 382

Rich comparison operators 386

Augmented assignment operators 390

Chapter summary 394

Further reading 395

Part V. Control flow

14. Iterables, iterators and generators. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . 403

Sentence take #1: a sequence of words 404

Why sequences are iterable: the iter function 406

Iterables versus iterators 407

Sentence take #2: a classic iterator 411

Making Sentence an iterator: bad idea 413

Sentence take #3: a generator function 414

How a generator function works 415

Sentence take #4: a lazy implementation 418

Sentence take #5: a generator expression 419

Generator expressions: when to use them 421

Another example: arithmetic progression generator 422

Arithmetic progression with itertools 425

Generator functions in the standard library 426

New syntax in Python 3.3: yield from 435

Iterable reducing functions 436

A closer look at the iter function 438

Case study: generators in a database conversion utility 439

Generators as coroutines 441

Chapter summary 442

Further reading 442

15. Context managers and else blocks. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . 449

Do this, then that: else blocks beyond if 450

Context managers and with blocks 452

The contextlib utilities 456

Using @contextmanager 457

Chapter summary 461

Further reading 461

Table of Contents | xi

16. Coroutines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . 465

How coroutines evolved from generators 466

Basic behavior of a generator used as a coroutine 466

Example: coroutine to compute a running average 470

Decorators for coroutine priming 471

Coroutine termination and exception handling 473

Returning a value from a coroutine 477

Using yield from 479

The meaning of yield from 485

Use case: coroutines for discrete event simulation 491

About discrete event simulations 491

The taxi fleet simulation 492

Chapter summary 500

Further reading 502

17. Concurrency with futures. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . 507

Example: Web downloads in three styles 507

A sequential download script 509

Downloading with concurrent.futures 511

Where are the futures? 513

Blocking I/O and the GIL 517

Launching processes with concurrent.futures 517

Experimenting with Executor.map 519

Downloads with progress display and error handling 522

Error handling in the flags2 examples 527

Using futures.as_completed 529

Threading and multiprocessing alternatives. 532

Chapter Summary 532

Further reading 533

18. Concurrency with asyncio. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . 539

Thread versus coroutine: a comparison 541

asyncio.Future: non-blocking by design 547

Yielding from futures, tasks and coroutines 548

Downloading with asyncio and aiohttp 550

Running circles around blocking calls 554

Enhancing the asyncio downloader script 556

Using asyncio.as_completed 557

Using an executor to avoid blocking the event loop 562

From callbacks to futures and coroutines 564

Doing multiple requests for each download 566

Writing asyncio servers 569

xii | Table of Contents

An asyncio TCP server 570

An aiohttp Web server 575

Smarter clients for better concurrency 578

Chapter Summary 579

Further reading 580

Part VI. Metaprogramming

19. Dynamic attributes and properties. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . 587

Data wrangling with dynamic attributes 588

Exploring JSON-like data with dynamic attributes 590

The invalid attribute name problem 593

Flexible object creation with __new__ 594

Restructuring the OSCON feed with shelve 596

Linked record retrieval with properties 600

Using a property for attribute validation 606

LineItem take #1: class for an item in an order 606

LineItem take #2: a validating property 607

A proper look at properties 609

Properties override instance attributes 610

Property documentation 612

Coding a property factory 613

Handling attribute deletion 616

Essential attributes and functions for attribute handling 618

Special attributes that affect attribute handling 618

Built-in functions for attribute handling 618

Special methods for attribute handling 619

Chapter summary 621

Further reading 621

20. Attribute descriptors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . 627

Descriptor example: attribute validation 627

LineItem take #3: a simple descriptor 628

LineItem take #4: automatic storage attribute names 633

LineItem take #5: a new descriptor type 639

Overriding versus non-overriding descriptors 642

Overriding descriptor 644

Overriding descriptor without __get__ 645

Non-overriding descriptor 646

Overwriting a descriptor in the class 647

Methods are descriptors 648

Table of Contents | xiii

Descriptor usage tips 650

1. Use property to keep it simple 650

2. Read-only descriptors require __set__ 650

3. Validation descriptors can work with __set__ only 650

4. Caching can be done efficiently with __get__ only 651

5. Non-special methods can be shadowed by instance attributes 651

Descriptor docstring and overriding deletion 652

Chapter summary 653

Further reading 653

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

. . . . . . . . . . . . . . . . . . . . . . . 657

A class factory 658

A class decorator for customizing descriptors 661

What happens when: import time versus run time 663

The evaluation time exercises 664

Metaclasses 101 668

The metaclass evaluation time exercise 670

A metaclass for customizing descriptors 674

The metaclass __prepare__ special method 676

Classes as objects 678

Chapter summary 679

Further reading 680

Afterword. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . 685

A. Support scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . 689

Python jargon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . 717

xiv | Table of Contents

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>1.

— 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

of the official Python Tutorial. That 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.”

xv

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

most differences can be learned in an afternoon. What’s New In

Python 3.0 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 Python Tutorial. Topics 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 example, 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.

xvi | Preface

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 implement 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.

Preface | xvii

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, doctest, works by

simulating 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

with doctest, take a look at its documentation and this book’s source
code repository.

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.

xviii | Preface

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 Python jargon 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

“The new @ infix operator in Python 3.5” on page 385 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 examples in Chapter 4, and the exceptions already noted for

Python 3 versions

earlier than 3.3.

Preface | xix
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») 2

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.

xx | Preface
Using Code Examples

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

entpython/example-code repository on Github.

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

for download at

https://github.com/oreillymedia/title_title.

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,

feel free to contact us at permissions@oreilly.com.

Safari® Books Online

Safari Books Online is an on-demand digital library that delivers

expert content 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 Books Online offers a range of product mixes and pricing

programs for organi‐
zations, government agencies, and individuals. Subscribers have
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‐

ogy, and dozens more. For more information about Safari Books
Online, please visit us

online.

Preface | xxi

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

information. You can access this page at

http://www.oreilly.com/catalog/<catalog page> .

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

bookques

tions@oreilly.com.

For more information about our books, courses, conferences, and

news, see our website

at http://www.oreilly.com.

Find us on Facebook: http://facebook.com/oreilly

Follow us on Twitter: http://twitter.com/oreillymedia

Watch us on YouTube: http://www.youtube.com/oreillymedia

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.

Alex’s 5000+ answers in Stack Overflow 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 xxii | Preface

an asyncio maintainer to the technical review team. It was a great

privilege and a pleasure to collaborate with them over these last
several months.

Editor Meghan Blanchette was an outstanding mentor, helping me

improve the orga‐
Other documents randomly have
different content
empoisonnée, mortelle, du monde civilisé… Chez nous, rien de
pareil… vous verrez!… Je possède à Canton, parmi des jardins
merveilleux, un palais où tout est disposé pour la vie libre et pour
l'amour… Que craignez-vous?… que laissez-vous?… qui donc
s'inquiète de vous!… Quand vous ne m'aimerez plus, ou quand vous
serez trop malheureux… vous vous en irez!…

—Clara!… Clara!… implorai-je…

Elle frappa, d'un coup sec, le plancher du navire:

—Vous ne me connaissez pas encore…, dit-elle… vous ne savez pas

qui je suis, et déjà vous voulez me quitter!… Est-ce que je vous fais
peur?… Est-ce que vous êtes lâche?

—Sans toi, je ne puis plus vivre!… sans toi, je ne puis que mourir!…

—Eh bien!… ne tremble plus… ne pleure plus… Et viens avec moi!…

Un éclair traversa le vert de ses prunelles. Elle dit d'une voix plus
basse, presque rauque:

—Je t'apprendrai des choses terribles… des choses divines… tu

sauras enfin ce que c'est que l'amour!… Je te promets que tu
descendras, avec moi, tout au fond du mystère de l'amour… et de la
mort!…

Et, souriant d'un sourire rouge qui me fit courir un frisson dans les
moelles, elle dit encore:

—Pauvre bébé!… Tu te croyais un grand débauché… un grand

révolté… Ah! tes pauvres remords… te souviens-tu?… Et voilà que
ton âme est plus timide que celle d'un petit enfant!…

C'était vrai!… j'avais beau me vanter d'être une intransigeante

canaille, me croire supérieur à tous les préjugés moraux, j'écoutais
encore, parfois, la voix du devoir et de l'honneur qui, à de certains
moments de dépression nerveuse, montait des profondeurs troubles
de ma conscience… L'honneur de qui?… le devoir de quoi?… Quel
abîme de folie que l'esprit de l'homme!… En quoi mon honneur—
mon honneur!—était-il compromis, en quoi déserterais-je mon devoir
parce que, au lieu de me morfondre à Ceylan, je poursuivrais mon
voyage jusqu'en Chine?… Est-ce que, véritablement, j'entrais assez
dans la peau d'un savant pour imaginer que j'allais «étudier la gelée
pélasgique», découvrir «la cellule», en plongeant dans les golfes de
la côte cynghalaise?… Cette idée tout à fait burlesque que j'eusse
pris au sérieux ma mission d'embryologiste, me ramena vite aux
réalités de ma situation… Comment!… la chance, le miracle voulait
que je rencontrasse une femme divinement belle, riche,
exceptionnelle, et que j'aimais et qui m'aimait, et qui m'offrait une
vie extraordinaire, des jouissances à foison, des sensations uniques,
des aventures libertines, une protection fastueuse… le salut, enfin…
et, plus que le salut… la joie!… Et je laisserais échapper tout cela!…
Une fois de plus, le démon de la perversité—ce stupide démon à qui,
pour lui avoir stupidement obéi, je devais tous mes malheurs—
interviendrait encore pour me conseiller une résistance hypocrite
contre un événement inespéré, qui tenait des contes de fées, qui ne
se retrouverait jamais plus, et dont je souhaitais ardemment, au
fond de moi-même qu'il se réalisât?… Non… non!… C'était trop bête,
à la fin!

—Vous avez raison, dis-je à Clara, en mettant sur le seul compte de

la défaite amoureuse une soumission qui contentait aussi tous mes
instincts de paresse et de débauche, vous avez raison… Je ne serais
pas digne de vos yeux, de votre bouche, de votre âme… de tout ce
paradis et de tout cet enfer, qui est vous… si j'hésitais plus
longtemps… Et puis… je ne pourrais pas… je ne pourrais pas te
perdre… Tout concevoir, hormis cela… Tu as raison… Je suis à toi…
emmène-moi où tu voudras… Souffrir… mourir… il n'importe!…
puisque tu es, toi que je ne connais pas encore, mon destin!…

—Ô bébé!… bébé!… bébé!… fit Clara sur un ton singulier, dont je ne

sus pas démêler l'expression véritable, et si c'était de la joie, de
l'ironie ou de la pitié!

Puis, presque maternelle, elle me recommanda:

—Maintenant… ne vous occupez de rien que d'être heureux… Restez

là… regardez l'île merveilleuse… Je vais régler avec le commissaire
votre nouvelle situation à bord…

—Clara…

—Ne craignez rien… Je sais ce qu'il faut dire…

Et comme j'allais émettre une objection:

—Chut!… N'êtes-vous pas mon bébé, cher petit cœur?… Vous devez
obéir… Et puis, vous ne savez pas…

Et elle disparut, se mêlant à la foule des passagers entassés sur le

pont, et dont beaucoup portaient déjà leurs valises et leurs menus
bagages.

Il avait été décidé que, les deux jours que nous relâchions à
Colombo, nous les passerions, Clara et moi, à visiter la ville et les
environs, où mon amie avait séjourné et qu'elle connaissait à
merveille. Il y faisait une chaleur torride, si torride que les endroits
les plus frais—par comparaison—de cet atroce pays, où des savants
placent le Paradis terrestre, tels les jardins au bord des grèves, me
parurent d'étouffantes étuves. La plupart de nos compagnons de
voyage n'osèrent pas affronter cette température de feu, qui leur
enlevait la moindre velléité de sortir et jusqu'au plus vague désir de
remuer. Je les vois encore, ridicules et gémissants, dans le grand hall
de l'hôtel, le crâne couvert de serviettes mouillées et fumantes,
élégant appareil renouvelé tous les quarts d'heure, qui transformait
la plus noble partie de leur individu en un tuyau de cheminée,
couronné de son panache de vapeur. Étendus sur des fauteuils à
bascule, sous le punka, la cervelle liquéfiée, les poumons
congestionnés, ils buvaient des boissons glacées que leur
préparaient des boys, lesquels, par la couleur de la peau et la
structure du corps, rappelaient les naïfs bonshommes en pain
d'épice de nos foires parisiennes, tandis que d'autres boys, de même
ton et de même gabarit, éloignaient d'eux, à grands coups
d'éventail, les moustiques.

Quant à moi, je retrouvai—un peu trop vite, peut-être,—toute ma

gaieté, et même toute ma verve blagueuse. Mes scrupules s'étaient
évanouis; je ne me sentais plus en mal de poésie. Débarrassé de
mes soucis, sûr de l'avenir, je redevins l'homme que j'étais en
quittant Marseille, le Parisien stupide et frondeur «à qui on ne la fait
pas», le boulevardier «qui ne s'en laisse pas conter», et qui sait dire
son fait à la nature… même des Tropiques!…

Colombo me parut une ville assommante, ridicule, sans pittoresque

et sans mystère. Moitié protestante, moitié bouddhiste, abrutie
comme un bonze et renfrognée comme un pasteur, avec quelle joie
je me félicitai, intérieurement, d'avoir, par miracle, échappé à l'ennui
profond que ses rues droites, son ciel immobile, ses dures
végétations dégageaient… Et je fis des mots d'esprit sur les cocotiers
que je ne manquai pas de comparer à d'affreux et chauves
plumeaux, ainsi que sur toutes les grandes plantes que j'accusai
d'avoir été taillées par de sinistres industriels dans des tôles peintes
et des zincs vernis… En nos promenades à Slave-Island, qui est le
Bois de l'endroit, et à Pettah, qui en est le quartier Mouffetard, nous
ne rencontrâmes que d'horribles Anglaises d'opérette, fagotées de
costumes clairs, mi-hindous, mi-européens, du plus carnavalesque
effet; et des Cynghalaises, plus horribles encore que les Anglaises,
vieilles à douze ans, ridées comme des pruneaux, tordues comme de
séculaires ceps de vigne, effondrées comme des paillotes en ruine,
avec des gencives en plaies saignantes, des lèvres brûlées par la
noix d'arec et des dents couleur de vieille pipe… Je cherchai en vain
les femmes voluptueuses, les négresses aux savantes pratiques
d'amour, les petites dentellières si pimpantes, dont m'avait parlé ce
menteur d'Eugène Mortain, avec des yeux si significativement
égrillards… Et je plaignis de tout mon cœur les pauvres savants que
l'on envoie ici, avec la problématique mission de conquérir le secret
de la vie.

Mais je compris que Clara ne goûtait pas ces plaisanteries faciles et

grossières, et je crus prudent de les atténuer, ne voulant ni la blesser
dans son culte fervent de la nature, ni me diminuer dans son esprit.
À plusieurs reprises, j'avais remarqué qu'elle m'écoutait avec un
étonnement pénible.

—Pourquoi donc êtes-vous si gai? m'avait-elle dit… Je n'aime pas

qu'on soit gai ainsi, cher petit cœur… Cela me fait du mal… Quand
on est gai, c'est que l'on n'aime pas… L'amour est une chose grave,
triste et profonde…

Ce qui ne l'empêchait pas, d'ailleurs, d'éclater de rire à propos de

tout ou à propos de rien…

C'est ainsi qu'elle m'encouragea fort dans une mystification dont

j'eus l'idée et que voici.

Parmi les lettres de recommandation que j'avais emportées de Paris,

s'en trouvait une pour un certain sir Oscar Terwick, lequel, entre
autres titres scientifiques, était, à Colombo, le président de
l'Association of the tropical embryology and of the british
entomology. À l'hôtel où je me renseignai, j'appris, en effet, que sir
Oscar Terwick était un homme considérable, auteur de travaux
renommés, un très grand savant, en un mot. Je résolus de l'aller
voir. Une telle visite ne pouvait plus m'être dangereuse, et puis je
n'étais pas fâché de connaître, de toucher un véritable
embryologiste. Il demeurait loin, dans un faubourg appelé Kolpetty
et qui est, pour ainsi dire, le Passy de Colombo. Là, au milieu de
jardins touffus, ornés de l'inévitable cocotier, dans des villas
spacieuses et bizarres, habitent les riches commerçants et les
notables fonctionnaires de la ville. Clara désira m'accompagner. Elle
m'attendit, en voiture, non loin de la maison du savant, sur une
sorte de petite place ombragée par d'immenses tecks.

Sir Oscar Terwick me reçut poliment—sans plus.

C'était un homme très long, très mince, très sec, très rouge de
visage, et dont la barbe blanche descendait jusqu'au nombril,
coupée carrément, ainsi qu'une queue de poney. Il portait un large
pantalon de soie jaune, et son torse velu s'enveloppait dans une
sorte de châle de laine claire. Il lut avec gravité la lettre que je lui
remis et, après m'avoir examiné du coin de l'œil avec un air méfiant
—se méfiait-il de moi ou de lui?—il me demanda:

—Vô… etè… embryologist?…

Je m'inclinai en signe d'assentiment…

—All right! gloussa-t-il…

Et faisant le geste de traîner un filet dans la mer, il reprit:

—Vô… etè… embryologist?… Yès… Vô… comme ça… dans le mer…

fish… fish… little fish?

—Little fish… parfaitement… little fish… appuyai-je, en répétant le

geste imitatif du savant.

—Dans le mer?…

—Yès!… Yès…

—Très intéressant!… très joli… très curious!… Yès!

Tout en jargonnant de la sorte—et continuant, tous les deux, de

traîner «dans le mer» nos chimériques filets—, le considérable
savant m'amena devant une console de bambou, sur laquelle étaient
rangés trois bustes de plâtre, couronnés de lotus artificiels. Les
désignant du doigt, successivement, il me les présenta, sur un ton
de gravité si comique que je faillis éclater de rire.

—Master Darwin!… très grand nat'raliste… très, très… grand!…

Yès!…

Je saluai profondément.

—Master Haeckel… très grand nat'raliste… Pas si que loui, non!…

Mais très grand!… Master Haeckel ici… comme ça… loui… dans le
mer… little fish…

Je saluai encore. Et d'une voix plus forte, il cria, en posant toute sa

main, rouge comme un crabe sur le troisième buste:

—Master Coqueline!… très grand nat'raliste… du miouséum…

comment appelez?… du miouséum Grévin… Yès!… Grévine!… Très
joli… très curious!…

—Très int'réssant! confirmai-je.

—Yès!…

Après quoi il me congédia.

Je fis à Clara le récit détaillé et mimé de cette étrange entrevue…

Elle rit comme une folle.

—Ô bébé!… bébé… bébé… que vous êtes drôle, cher petit voyou!…

Ce fut le seul épisode scientifique de ma mission. Et je compris alors

ce que c'était que l'embryologie!
Le lendemain matin, après une sauvage nuit d'amour, nous
reprenions la mer, en route vers la Chine.
 DEUXIÈME PARTIE
LE JARDIN DES SUPPLICES

—Pourquoi ne m'avez-vous pas encore parlé de notre chère Annie?…

Ne lui avez-vous pas appris mon arrivée ici?… Est-ce qu'elle ne
viendra pas aujourd'hui?… Est-ce qu'elle est toujours belle?

—Comment?… Vous ne savez pas?… Mais Annie est morte, cher petit
cœur…

—Morte! m'écriai-je… Ce n'est pas possible… Vous voulez me

taquiner…

Je regardai Clara. Divinement calme et jolie, nue dans une

transparente tunique de soie jaune, elle était mollement couchée sur
une peau de tigre. Sa tête reposait parmi des coussins, et de ses
mains, chargées de bagues, elle jouait avec une longue mèche de
ses cheveux déroulés. Un chien du Laos, aux poils rouges, dormait
auprès d'elle, le museau sur sa cuisse, une patte sur son sein.

—Comment?… reprit Clara… vous ne saviez pas?… Comme c'est

drôle!
Et, toute souriante, avec des étirements de souple animal, elle
m'expliqua:

—Ce fut quelque chose d'horrible, chéri! Annie est morte de la

lèpre… de cette lèpre effrayante qu'on appelle l'éléphantiasis… Car
tout est effrayant ici… l'amour, la maladie… la mort… et les fleurs!…
Jamais je n'ai tant, tant pleuré, je vous assure… Je l'aimais tant,
tant! Et elle était si belle, si étrangement belle!…

Elle ajouta, dans un long et gracieux soupir:

—Jamais plus nous ne connaîtrons le goût si âpre de ses baisers!…

C'est un grand malheur!

—Alors… c'est donc vrai?… balbutiai-je… Mais comment cela est-il

arrivé?

—Je ne sais… Il y a tant de mystères ici… tant de choses qu'on ne

comprend pas… Toutes les deux, nous allions souvent, le soir, sur le
fleuve… Il faut vous dire qu'il y avait alors dans un bateau de
fleurs… une bayadère de Bénarès… une affolante créature, chéri, à
qui des prêtres avaient enseigné certains rites maudits des anciens
cultes brahmaniques… C'est peut-être cela… ou autre chose… Une
nuit que nous revenions du fleuve, Annie se plaignit de très vives
douleurs à la tête et aux reins. Le lendemain, son corps était tout
couvert de petites taches pourprées… Sa peau, plus rose et d'une
plus fine pulpe que la fleur de l'althœa se durcit, s'épaissit, s'enfla,
devint d'un gris cendreux… de grosses tumeurs, de monstrueux
tubercules la soulevèrent. C'était quelque chose d'épouvantable. Et
le mal qui, d'abord, s'était attaqué aux jambes, gagna les cuisses, le
ventre, les seins, le visage… Oh! son visage, son visage!… Figurez-
vous une poche énorme, une outre ignoble, toute grise, striée de
sang brun… et qui pendait et qui se balançait au moindre
mouvement de la malade… De ses yeux—ses yeux, cher amour!—on
ne voyait plus qu'une mince boutonnière rougeâtre et suintante… Je
me demande encore si c'est possible!
Elle enroula autour de ses doigts la mèche dorée. Dans un
mouvement, la patte du chien endormi, ayant glissé sur la soie,
découvrit entièrement le globe du sein qui darda sa pointe, rose
comme une jeune fleur.

—Oui, je me demande encore, parfois, si je ne rêve pas… dit-elle.

—Clara… Clara! suppliai-je, éperdu d'horreur… ne me dites plus

rien… Je voudrais que l'image de notre divine Annie restât intacte
dans mon souvenir… Comment ferai-je, maintenant, pour éloigner de
ma pensée ce cauchemar?… Ah! Clara, ne dites plus rien, ou parlez-
moi d'Annie, quand elle était si belle… quand elle était trop belle!…

Mais Clara ne m'écoutait pas. Elle poursuivit:

—Annie s'isola… se claustra dans sa maison, seule avec une

gouvernante chinoise qui la soignait… Elle avait renvoyé toutes ses
femmes et ne voulait plus voir personne… pas même moi… Elle fit
venir les plus habiles praticiens d'Angleterre… En vain, vous pensez
bien… Les plus célèbres sorciers du Thibet, ceux-là qui connaissent
les paroles magiques et ressuscitent les morts, se déclarèrent
impuissants… On ne guérit jamais de ce mal, mais on n'en meurt
pas non plus… C'est affreux!… Alors elle se tua… Quelques gouttes
de poison, et ce fut fini de la plus belle des femmes.

L'épouvante me clouait les lèvres. Je regardai Clara, sans avoir l'idée

d'une seule parole.

—J'ai appris de cette Chinoise, continua Clara, un détail vraiment

curieux… et qui m'enchante… Vous savez combien Annie aimait les
perles… Elle en possédait d'incomparables… les plus merveilleuses,
je crois, qui fussent au monde… Vous vous souvenez aussi avec
quelle sorte de joie physique, de spasme charnel, elle s'en parait…
Eh bien, malade, cette passion lui était devenue une folie… une
fureur… comme l'amour!… Toute la journée, elle se plaisait à les
toucher, à les caresser, à les baiser; elle s'en faisait des coussins, des
colliers, des pèlerines, des manteaux… Mais il arriva cette chose
extraordinaire: les perles mouraient sur sa peau… elles se
ternissaient d'abord, peu à peu… peu à peu s'éteignaient… aucune
lumière ne se reflétait plus en leur orient… et, en quelques jours,
atteintes de la lèpre, elles se changeaient en de menues boules de
cendre… Elles étaient mortes… mortes comme des personnes, mon
cher amour… Saviez-vous qu'il y eût des âmes dans les perles?…
Moi, je trouve cela affolant et délicieux… Et, depuis, j'y pense tous
les jours…

Après un court silence, elle reprit:

—Et ce n'est pas tout!… Maintes fois, Annie avait manifesté le désir
d'être emportée, quand elle serait morte, au petit cimetière des
Parsis… là-bas… sur la colline du Chien Bleu… Elle voulait que son
corps fût déchiré par le bec des vautours… Vous savez combien elle
avait des idées singulières et violentes en toutes choses!… Eh bien,
les vautours refusèrent ce festin royal, qu'elle leur offrait… Ils
s'éloignèrent, en poussant d'affreux cris, de son cadavre… Il fallut le
brûler…

—Mais, pourquoi ne m'avez-vous pas écrit tout cela? reprochai-je à

Clara.

Avec des gestes lents et charmants, Clara lissa l'or roux de ses
cheveux, caressa la fourrure rouge du chien qui s'était réveillé, et
elle dit négligemment:

—Vraiment?… Je ne vous avais rien écrit de tout cela?… Vous êtes

sûr?… Je l'ai oublié sans doute… Pauvre Annie!

Elle dit encore:

—Depuis ce grand malheur… tout m'ennuie ici… Je suis trop seule…

Je voudrais mourir… mourir… moi aussi… ah, je vous assure!… Et si
vous n'étiez pas revenu, je crois bien que je serais déjà morte…
Elle renversa sa tête sur les coussins, agrandit l'espace nu de sa
poitrine…, et avec un sourire… un étrange sourire d'enfant et de
prostituée, tout ensemble:

—Est-ce que mes seins vous plaisent toujours?… Est-ce que vous me
trouvez toujours belle?… Alors, pourquoi êtes-vous parti si… si
longtemps? Oui… oui… je sais… ne dites rien… ne répondez rien… je
sais… Vous êtes une petite bête, cher amour!…

J'aurais bien voulu pleurer; je ne le pus… J'aurais bien voulu parler

encore; je ne le pus davantage…

Et nous étions dans le jardin, sous le kiosque doré, où des glycines

retombaient en grappes bleues, en grappes blanches; et nous
finissions de prendre le thé… D'étincelants scarabées bourdonnaient
dans les feuilles, des cétoines vibraient et mouraient au cœur pâmé
des roses, et, par la porte ouverte, du côté du nord, nous voyions se
lever d'un bassin, autour duquel dormaient des cigognes dans une
ombre molle et toute mauve, les longues tiges des iris jaunes,
flammés de pourpre.

Tout à coup, Clara me demanda:

—Voulez-vous que nous allions donner à manger aux forçats

chinois?… C'est très curieux… très amusant… C'est même la seule
distraction vraiment originale et élégante que nous ayons, dans ce
coin perdu de la Chine… Voulez-vous, petit amour?…

Je me sentais fatigué, la tête lourde, tout mon être envahi par la

fièvre de cet effrayant climat… De plus, le récit de la mort d'Annie
m'avait bouleversé l'âme… Et, la chaleur, au-dehors, était mortelle
comme un poison…

—J'ignore ce que vous me demandez, chère Clara… mais je ne suis

pas remis de ce long voyage à travers les plaines et les plaines… les
forêts et les forêts… Et ce soleil… je le redoute plus que la mort!… Et
puis, j'aurais tant voulu être tout à vous… et que vous fussiez tout à
moi, aujourd'hui…

—C'est cela!… Si nous étions en Europe, et que je vous eusse

demandé de m'accompagner aux courses, au théâtre, vous n'auriez
pas hésité… Mais c'est bien plus beau que les courses.

—Soyez bonne!… Demain, voulez-vous?

—Oh! demain… répondit Clara, avec des moues étonnées et des airs
de doux reproche… toujours demain!… Vous ne savez donc pas que
c'est impossible demain?… Demain?… mais c'est tout à fait
défendu… Les portes du bagne sont fermées… même pour moi… On
ne peut donner à manger aux forçats que le mercredi; comment ne
le savez-vous pas?… Si nous manquons cette visite aujourd'hui, il
nous faudra attendre, toute une longue, longue semaine… Comme
ce serait ennuyeux!… Toute une semaine, pensez donc!… Venez,
petite chiffe adorée… oh! venez, je vous en prie… Vous pouvez bien
faire cela pour moi…

Elle se souleva à demi, sur les coussins… La tunique écartée laissa

voir, plus bas que la taille, entre les nuages de l'étoffe, des coins de
sa chair ardente et rose. D'une bonbonnière d'or, posée sur un
plateau de laque, elle tira, du bout de ses doigts, un cachet de
quinine, et, m'ordonnant de m'approcher, elle le porta, gentiment, à
mes lèvres.

—Vous verrez comme c'est passionnant… tellement passionnant!…

Vous n'avez pas idée, chéri… Et comme je vous aimerai mieux ce
soir!… comme je t'aimerai follement, ce soir!… Avale, cher petit
cœur… avale…

Et comme j'étais toujours triste, hésitant, pour vaincre mes dernières

résistances, elle dit, avec des lueurs sombres, dans ses yeux…

—Écoute!… J'ai vu pendre des voleurs en Angleterre, j'ai vu des

courses de taureaux et garrotter des anarchistes en Espagne… En
Russie, j'ai vu fouetter par des soldats, jusqu'à la mort, de belles
jeunes filles… En Italie, j'ai vu des fantômes vivants, des spectres de
famine déterrer des cholériques et les manger avidement… J'ai vu,
dans l'Inde, au bord d'un fleuve, des milliers d'êtres, tout nus, se
tordre et mourir dans les épouvantes de la peste… À Berlin, un soir,
j'ai vu une femme que j'avais aimée la veille, une splendide créature
en maillot rose, je l'ai vue, dévorée par un lion, dans une cage…
Toutes les terreurs, toutes les tortures humaines, je les ai vues…
C'était très beau!… Mais je n'ai rien vu de si beau… comprends-tu?…
que ces forçats chinois… c'est plus beau que tout!… Tu ne peux pas
savoir… je te dis que tu ne peux pas savoir… Annie et moi, nous ne
manquions jamais un mercredi… Viens, je t'en prie!

—Puisque c'est si beau, ma chère Clara… et que cela vous fait tant
de plaisir… répondis-je mélancoliquement… allons donner à manger
aux forçats…

—Vrai, tu veux bien?…

Clara manifesta sa joie, en tapant dans ses mains, comme un baby à

qui sa gouvernante vient de permettre de torturer un petit chien.
Puis elle sauta sur mes genoux, caressante et féline, m'entoura le
cou de ses bras… Et sa chevelure m'inonda, m'aveugla le visage de
flammes d'or et de grisants parfums…

—Que tu es gentil… cher… cher amour… Embrasse mes lèvres…

embrasse ma nuque… embrasse mes cheveux… cher petit voyou!…

Sa chevelure avait une odeur animale si puissante et de si

électriques caresses que son seul contact, sur ma peau, me faisait
instantanément oublier fièvres, fatigues et douleurs… et je sentais
aussitôt circuler, galoper en mes veines d'héroïques ardeurs et des
forces nouvelles…

—Ah! comme nous allons nous amuser, chère petite âme… Quand je
vais aux forçats… ça me donne le vertige… et j'ai, dans tout le corps,
des secousses pareilles à de l'amour… il me semble, vois-tu… il me
semble que je descends au fond de ma chair… tout au fond des
ténèbres de ma chair… Ta bouche… donne-moi ta bouche… ta
bouche… ta bouche… ta bouche!…

Et leste, preste, impudique et joyeuse, suivie du chien rouge qui

bondissait, elle alla se remettre aux mains des femmes, chargées de
l'habiller…

Je n'étais plus très triste, je n'étais plus très las… Le baiser de Clara,
dont j'avais, sur les lèvres, le goût—comme un magique goût
d'opium—insensibilisait mes souffrances, ralentissait les pulsations
de ma fièvre, éloignait jusqu'à l'invisible l'image monstrueuse d'Annie
morte… Et je regardai le jardin d'un regard apaisé…

Apaisé?…

Le jardin descendait en pentes douces, orné partout d'essences

rares et de précieuses plantes… Une allée d'énormes camphriers
partait du kiosque où j'étais, aboutissait à une porte rouge, en forme
de temple, qui donnait sur la campagne… Entre les branches
feuillues des arbres gigantesques masquant, à gauche, la vue,
j'apercevais, par places, le fleuve qui luisait, comme de l'argent poli,
sous le soleil… J'essayai de m'intéresser aux multiples décorations du
jardin… à ses fleurs étranges, à ses monstrueuses végétations… Un
homme traversa l'allée, qui conduisait en laisse deux panthères
indolentes… Ici, au milieu d'une pelouse, se dressait un immense
bronze, représentant je ne sais quelle divinité, obscène et cruelle…
Là, des oiseaux, grues à manteau bleu, toucans à gorge rouge de
l'Amérique tropicale, faisans vénérés, canards casqués et cuirassés
d'or, vêtus de pourpres éclatantes comme d'antiques guerriers,
longirostres multicolores, cherchaient l'ombre, au bord des massifs…
Mais, ni les oiseaux, ni les fauves, ni les Dieux, ni les fleurs ne
pouvaient fixer mon attention, ni le bizarre palais qui, à ma droite,
entre les cedrèles et les bambous, superposait ses claires terrasses
garnies de fleurs, ses balcons ombreux et ses toits coloriés… Ma
pensée était ailleurs… très loin, très loin… par-delà les mers et les
forêts… Elle était en moi… sombrée en moi… au plus profond de
moi!…

Apaisé?…

À peine Clara eut-elle disparu derrière les feuillages du jardin que le

remords d'être là me saisit… Pourquoi étais-je revenu?… À quelle
folie, à quelle lâcheté avais-je donc obéi?… Elle m'avait dit un jour,
vous vous souvenez, sur le bateau: «Quand vous serez trop
malheureux, vous vous en irez!»… Je me croyais fort de tout mon
passé infâme… et je n'étais, en effet, qu'un enfant débile et inquiet…
Malheureux?… Ah oui! je l'avais été, jusqu'aux pires tortures,
jusqu'au plus prodigieux dégoût de moi-même… Et j'étais parti!…
Par une ironie vraiment persécutrice, j'avais profité, pour fuir Clara,
du passage à Canton d'une mission anglaise—j'étais décidément
voué aux missions—qui allait explorer les régions peu connues de
l'Annam… C'était l'oubli, peut-être… et peut-être la mort. Durant
deux années, deux longues et cruelles années, j'avais marché…
marché… Et ce n'avait été ni l'oubli, ni la mort… Malgré les fatigues,
les dangers, la fièvre maudite, pas un jour, pas une minute, je
n'avais pu me guérir de l'affreux poison qu'avait déposé, dans ma
chair, cette femme dont je sentais que ce qui m'attachait à elle, que
ce qui me rivait à elle, c'était l'effrayante pourriture de son âme et
ses crimes d'amour, qui était un monstre, et que j'aimais d'être un
monstre!… J'avais cru—l'ai-je cru vraiment?—me relever par son
amour… et voilà que j'étais descendu plus bas, au fond du gouffre
empoisonné dont, quand on en a une fois respiré l'odeur, on ne
remonte jamais plus. Souvent, au fond des forêts, hanté de la fièvre,
après les étapes—sous ma tente—j'avais cru tuer, par l'opium, la
monstrueuse et persistante image… Et l'opium me l'évoquait plus
formelle, plus vivante, plus impérieuse que jamais… Alors, je lui
avais écrit des lettres folles, injurieuses, imprécatoires, des lettres où
l'exécration la plus violente se mêlait à la plus soumise adoration…
Elle m'avait répondu des lettres charmantes, inconscientes et
plaintives, que je trouvais, parfois, dans les villes et les postes où
nous passions… Elle-même se disait malheureuse de mon abandon…
pleurait, suppliait… me rappelait. Elle ne trouvait pas d'autres
excuses que celle-ci: «Comprends donc, mon chéri—m'écrivait-elle—
que je n'ai pas l'âme de ton affreuse Europe… Je porte, en moi,
l'âme de la vieille Chine, qui est bien plus belle… Est-ce désolant que
tu ne puisses te faire à cette idée?»… J'appris, ainsi, par une de ses
lettres, qu'elle avait quitté Canton où elle ne pouvait plus vivre sans
moi, pour venir avec Annie habiter une ville plus au sud de la Chine,
«qui était merveilleuse»… Ah! comment ai-je pu si longtemps
résister au mauvais désir d'abandonner mes compagnons et de
gagner cette ville maudite et sublime, ce délicieux et torturant enfer,
où Clara respirait, vivait… en des voluptés inconnues et atroces, dont
je mourais maintenant de ne plus prendre ma part… Et j'étais revenu
à elle, comme l'assassin revient au lieu même de son crime…

Des rires dans le feuillage, de petits cris… un bondissement de

chien… C'était Clara… Elle était vêtue, moitié à la chinoise, moitié à
l'européenne… Une blouse de soie mauve pâle, semée de fleurs à
peine dorées, l'enveloppait de mille plis, tout en dessinant son corps
svelte et ses formes pleines… Elle avait un grand chapeau de paille
blonde, au fond duquel son visage apparaissait, pareil à une fleur
rose dans de l'ombre claire… Et ses petits pieds étaient chaussés de
peau jaune… Quand elle entra dans le kiosque, ce fut comme une
explosion de parfums…

—Vous me trouvez drôlement fagotée, n'est-ce pas?… Ô l'homme

triste d'Europe, qui n'a pas ri, une seule fois, depuis qu'il est de
retour… Est-ce que je ne suis pas belle?…

Comme je ne me levais pas du divan où je m'étais allongé:

—Vite! vite!… mon chéri… Car il faut que nous fassions le grand
tour… Je mettrai mes gants en route… Allons… Venez!… Non… non…
pas vous!… ajouta-t-elle, en repoussant doucement le chien qui
jappait, bondissait, frétillait de la queue…
Elle appela un boy et lui recommanda de nous suivre avec le panier
à viande et la petite fourche.

—Ah! m'expliqua-t-elle… très amusant!… Un amour de panier tressé

par le meilleur vannier de la Chine… et la fourche… tu vas voir, une
amour de petite fourche dont les dents sont de platine incrusté d'or,
et le manche de jade vert… vert comme le ciel aux premières lueurs
du matin… vert comme étaient les yeux de la pauvre Annie!… Allons
ne faites pas cette vilaine figure d'enterrement, chéri… et venez
vite… vite…

Et nous nous mîmes en marche par le soleil, par l'affreux soleil qui
noircissait l'herbe, fanait toutes les pivoines du jardin, et me pesait
au crâne, ainsi qu'un lourd casque de plomb.

II

Le bagne est de l'autre côté de la rivière qui, au sortir de la ville,

déroule lentement, sinistrement, entre des berges plates, ses eaux
pestilentielles et toutes noires. Pour s'y rendre, il faut faire un long
détour, atteindre un pont sur lequel, tous les mercredis, au milieu
d'une affluence considérable de personnes élégantes, se tient le
marché de la Viande-aux-Forçats.

Clara avait refusé le palanquin. Nous descendîmes, à pied, le jardin

situé hors l'enceinte de la cité et, par un sentier, bordé ici de pierres
brunes, là d'épaisses haies de roses blanches ou de troènes taillés,
nous gagnâmes les faubourgs, à cet endroit où la ville diminuée se
fait presque la campagne, où les maisons, devenues des cahutes,
s'espacent, de loin en loin, dans de petits enclos, treillagés de
bambous. Ce ne sont, ensuite, que vergers en fleurs, cultures de
maraîchers ou terrains vagues. Des hommes nus jusqu'à la ceinture,
coiffés de chapeaux en forme de cloche, travaillaient péniblement
sous le soleil, et plantaient des lis—ces beaux lis tigrés dont les
pétales ressemblent à des pattes d'araignée marine, et dont les
bulbes savoureux servent à la nourriture des riches. Nous passâmes
ainsi devant quelques misérables hangars où des potiers tournaient
des pots, où des trieurs de chiffons, accroupis, parmi de vastes
corbeilles, inventoriaient la récolte du matin, tandis que passait et
repassait au-dessus d'eux, une bande de corors affamés et
croassants. Plus loin, sous un énorme figuier, nous vîmes, assis à la
margelle d'une fontaine, un doux et méticuleux vieillard qui lavait
des oiseaux. À chaque instant, nous croisions des palanquins qui
transportaient vers la ville des matelots européens, déjà ivres. Et,
derrière nous, ardente et tassée, escaladant la haute colline, la ville,
avec ses temples et ses étranges maisons rouges, vertes, jaunes,
crépitait dans la lumière.

Clara marchait vite, sans pitié pour ma fatigue, sans souci du soleil
qui embrasait l'atmosphère et, malgré nos parasols, nous brûlait la
peau; elle marchait libre, souple, hardie, heureuse. Parfois, sur un
ton de reproche enjoué, elle me disait:

—Que vous êtes lent, chéri… Dieu que vous êtes lent!… Vous
n'avancez pas… Pourvu que les portes du bagne ne soient pas
ouvertes quand nous arriverons et que les forçats ne soient pas
gavés!… Ce serait affreux!… Oh! comme je vous détesterais!

De temps en temps, elle me donnait des pastilles d'hamamélis, dont

la vertu est d'activer la respiration, et, les yeux moqueurs:

—Oh! petite femme!… petite femme… petite femme de rien du tout!

Puis, moitié rieuse, moitié fâchée, elle se mettait à courir… Et j'avais

beaucoup de peine à la suivre… Plusieurs fois, je dus m'arrêter et
reprendre haleine. Il me semblait que mes veines se rompaient, que
mon cœur éclatait dans ma poitrine.

Et Clara répétait, de sa voix gazouilleuse:

—Petite femme!… Petite femme de rien du tout!

Le sentier débouche sur le quai du fleuve. Deux grands steamers
débarquaient du charbon et des marchandises d'Europe; quelques
jonques appareillaient pour la pêche; une nombreuse flottille de
sampangs, avec ses tentes bigarrées, dormait à l'ancre, bercée par
le léger clapotement de l'eau. Pas un souffle ne passait dans l'air.

Ce quai m'offensa. Il était sale et défoncé, couvert de poussière

noire, jonché de vidures de poisson. De puantes odeurs, des bruits
de rixes, des chants de flûte, des abois de chien nous arrivaient du
fond des taudis qui le bordent: maisons de thé vermineuses,
boutiques en coupe-gorge, factoreries louches. Clara me montra, en
riant, une sorte de petite échoppe où l'on vendait, étalés sur des
feuilles de caladium, des portions de rats et des quartiers de chiens,
des poissons pourris, des poulets étiques, enduits de copal, des
régimes de bananes et des chauves-souris saignantes, enfilées sur
de mêmes broches…

À mesure que nous avancions, les odeurs se faisaient plus

intolérables, les ordures plus épaisses. Sur le fleuve, les bateaux se
pressaient, se tassaient, mêlant les becs sinistres de leurs proues et
les lambeaux déchirés de leurs pauvres voilures. Là vivait une
population dense—pêcheurs et pirates—affreux démons de la mer,
au visage boucané, aux lèvres rougies par le bétel, et dont les
regards vous donnaient le frisson. Ils jouaient aux dés, hurlaient, se
battaient; d'autres, plus pacifiques, éventraient des poissons qu'ils
faisaient ensuite sécher au soleil, en guirlandes, sur des cordes…
D'autres encore dressaient des singes à faire mille gentillesses et
obscénités.

—Amusants, pas?… me dit Clara… Et ils sont plus de trente mille qui
n'ont pas d'autre domicile que leurs bateaux!… Par exemple, le
diable seul sait ce qu'ils font!…

Elle releva sa robe, découvrit le bas de sa jambe agile et nerveuse,

et, longtemps, nous suivîmes l'horrible chemin, jusqu'au pont dont
les surconstructions bizarres et les cinq arches massives, peintes de
couleurs violentes, enjambent la rivière, sur laquelle, au gré des
remous et des courants, tournent, tournent et descendent de grands
cercles huileux.

Sur le pont, le spectacle change, mais l'odeur s'aggrave, cette odeur

si particulière à toute la Chine et qui, dans les villes, les forêts et les
plaines, vous fait songer, sans cesse, à la pourriture et à la mort.

De petites boutiques imitant les pagodes, des tentes en forme de

kiosque, drapées d'étoffes claires et soyeuses, d'immenses parasols,
plantés sur des chariots et des éventaires roulants, se pressent les
uns contre les autres. Dans ces boutiques, sous ces tentes et ces
parasols, de gros marchands, à ventre d'hippopotame, vêtus de
robes jaunes, bleues, vertes, hurlant et tapant sur des gongs, pour
attirer les clients, débitent des charognes de toute sorte: rats morts,
chiens noyés, quartiers de cerfs et de chevaux, purulentes volailles,
entassés, pêle-mêle, dans de larges bassines de bronze.

—Ici… ici… par ici!… venez par ici!… Et regardez!… et choisissez!…

Nulle part vous n'en trouverez de meilleure… Il n'y en a pas de plus
corrompue.

Et, fouillant dans les bassines, ils brandissent, comme des drapeaux,
au bout de longs crochets de fer, d'ignobles quartiers de viande
sanieuse, et, avec d'atroces grimaces qu'accentuent les rouges
balafres de leurs visages peints ainsi que des masques, ils répètent
parmi le retentissement enragé des gongs et les clameurs
concurrentes:

—Ici… ici… par ici!… Venez par ici… et regardez… et choisissez…

Nulle part, vous n'en trouverez de meilleure… Il n'y en a pas de plus
corrompue…

Dès que nous fûmes engagés sur le pont, Clara me dit:

—Ah! tu vois, nous sommes en retard. C'est de ta faute!…
Dépêchons-nous.

En effet, une foule nombreuse de Chinoises et, parmi elles, quelques

Anglaises et quelques Russes—car il n'y avait que fort peu
d'hommes, hormis les commissionnaires—grouillait sur le pont.
Robes brodées de fleurs et de métamorphoses, ombrelles
multicolores, éventails agiles comme des oiseaux, et des rires, et des
cris, et de la joie, et de la lutte, tout cela vibrait, chatoyait, chantait,
voletait dans le soleil, telle une fête de vie et d'amour.

—Ici… ici… par ici!… Venez par ici!…

Ahuri par la bousculade, étourdi par le glapissement des marchands

et les vibrations sonores des gongs, il fallut presque me battre pour
pénétrer dans la foule et pour protéger Clara contre les insultes des
unes, les coups des autres. Combat grotesque, en vérité, car j'étais
sans résistance et sans force, et je me sentais emporté dans ce
tumulte humain aussi facilement que l'arbre mort roulé dans les
eaux furieuses d'un torrent… Clara, elle, se jetait au plus fort de la
mêlée. Elle subissait le brutal contact et, pour ainsi dire, le viol de
cette foule, avec un plaisir passionné… Un moment, elle s'écria,
glorieusement:

—Vois, chéri… ma robe est toute déchirée… C'est délicieux!

Nous eûmes beaucoup de peine à nous frayer un passage jusqu'aux

boutiques encombrées, assiégées, comme pour un pillage.

—Regardez et choisissez!… Nulle part, vous n'en trouverez de

meilleure.

—Ici… ici… par ici!… Venez par ici!…

Clara prit l'amour de petite fourche des mains du boy qui nous
suivait avec son amour de panier, et elle piqua dans les bassines.
—Pique aussi, toi!… pique, cher amour!…

Je crus que le cœur allait me manquer, à cause de l'épouvantable

odeur de charnier qui s'exhalait de ces boutiques, de ces bassines
remuées, de toute cette foule, se ruant aux charognes, comme si
c'eût été des fleurs.

—Clara, chère Clara! implorai-je… Partons d'ici, je vous en prie!

—Oh! comme vous êtes pâle! Et pourquoi?… N'est-ce donc pas très
amusant?…

—Clara… chère Clara!… insistai-je… Partons d'ici, je vous en

supplie!… Il m'est impossible de supporter plus longtemps cette
odeur.

—Mais cela ne sent pas mauvais, mon amour… Cela sent la mort,
voilà tout!…

Elle ne semblait pas incommodée… Aucune grimace de dégoût ne

plissait sa peau blanche, aussi fraîche qu'une fleur de cerisier. Par
l'ardeur voilée de ses yeux, par le battement de ses narines, on eût
dit qu'elle éprouvait une jouissance d'amour… Elle humait la
pourriture, avec délices, comme un parfum.

—Oh! le beau… beau morceau!…

Avec des gestes gracieux, elle emplit le panier de l'immonde débris.

Et, péniblement, à travers la foule surexcitée, parmi les abominables

odeurs, nous continuâmes notre route.

—Vite!… vite!…

III