3.4.8 Coercion rules

##
3.4.8 Coercion rules

This section used to document the rules for coercion. As the language has evolved, the coercion rules have become hard to document precisely; documenting what one version of one particular implementation does is undesirable. Instead, here are some informal guidelines regarding coercion. In Python 3.0, coercion will not be supported.

- If the left operand of a % operator is a string or Unicode object, no coercion takes place and the string formatting operation is invoked instead.

- It is no longer recommended to define a coercion operation. Mixed-mode operations on types that don't define coercion pass the original arguments to the operation.

- New-style classes (those derived from `object`) never invoke the `__coerce__()` method in response to a binary operator; the only time `__coerce__()` is invoked is when the built-in function `coerce()` is called.

- For most intents and purposes, an operator that returns `NotImplemented` is treated the same as one that is not implemented at all.

- Below, `__op__()` and `__rop__()` are used to signify the generic method names corresponding to an operator; `__iop__()` is used for the corresponding in-place operator. For example, for the operator ``+`', `__add__()` and `__radd__()` are used for the left and right variant of the binary operator, and `__iadd__()` for the in-place variant.

- For objects x and y, first `x.__op__(y)` is tried. If this is not implemented or returns `NotImplemented`, `y.__rop__(x)` is tried. If this is also not implemented or returns `NotImplemented`, a `TypeError` exception is raised. But see the following exception:

- Exception to the previous item: if the left operand is an instance of a built-in type or a new-style class, and the right operand is an instance of a proper subclass of that type or class and overrides the base's `__rop__()` method, the right operand's `__rop__()` method is tried before the left operand's `__op__()` method.

  This is done so that a subclass can completely override binary operators. Otherwise, the left operand's `__op__()` method would always accept the right operand: when an instance of a given class is expected, an instance of a subclass of that class is always acceptable.

- When either operand type defines a coercion, this coercion is called before that type's `__op__()` or `__rop__()` method is called, but no sooner. If the coercion returns an object of a different type for the operand whose coercion is invoked, part of the process is redone using the new object.

- When an in-place operator (like ``+=`') is used, if the left operand implements `__iop__()`, it is invoked without any coercion. When the operation falls back to `__op__()` and/or `__rop__()`, the normal coercion rules apply.

- In x`+`y, if x is a sequence that implements sequence concatenation, sequence concatenation is invoked.

- In x`*`y, if one operator is a sequence that implements sequence repetition, and the other is an integer (`int` or `long`), sequence repetition is invoked.

- Rich comparisons (implemented by methods `__eq__()` and so on) never use coercion. Three-way comparison (implemented by `__cmp__()`) does use coercion under the same conditions as other binary operations use it.

- In the current implementation, the built-in numeric types `int`, `long` and `float` do not use coercion; the type `complex` however does use it. The difference can become apparent when subclassing these types. Over time, the type `complex` may be fixed to avoid coercion. All these types implement a `__coerce__()` method, for use by the built-in `coerce()` function.