I'm not sure if this is a documentation issue or a bug. If watchexp=0,
quantize() also allows any number of digits:

>>> x = Decimal("6885998238912213556789006667970467609814")
>>> y = Decimal("1e2")
>>> x.quantize(y)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/local/lib/python3.2/decimal.py", line 2488, in quantize
    'quantize result has too many digits for current context')
  File "/usr/local/lib/python3.2/decimal.py", line 3925, in _raise_error
    raise error(explanation)
decimal.InvalidOperation: quantize result has too many digits for current context
>>> 
>>> x.quantize(y, watchexp=0)
Decimal('6.8859982389122135567890066679704676098E+39')

NaNs, however, are decapitated:

>>> x = Decimal("NaN5357671565858315212612021522416387828577")
>>> y = 0
>>> x.quantize(y, watchexp=0)
Decimal('NaN8315212612021522416387828577')

Ping. We have to decide if we need watchexp in _decimal. I've left it
out so far since all I can gather from the docs is that it somehow
behaves like _rescale.

Can we deprecate it and replace it by a proper rescale?

I'd be happy to see watchexp deprecated. It feels like a leftover implementation artefact; its behaviour isn't properly defined anywhere, and as far as I can tell it has only a single testcase.

Does anyone know why watchexp was put there in the first place?

http://speleotrove.com/decimal/daops.html#refquant

If no motivation for this can be found, I agree with Mark that it should be deprecated and removed.

watchexp was available in rescale() from the beginning ...

http://svn.python.org/view/sandbox/trunk/decimal/Decimal.py?revision=40721&view=markup

... and rescale() was renamed to quantize() in

http://svn.python.org/view/sandbox/trunk/decimal/Decimal.py?revision=40909&view=markup

rescale() was once part of the specification, but had identical semantics to
quantize(), which is not specified to allow unlimited rescaling.

I suppose the original rescale() in the sandbox had watchexp for convenience,
in order to avoid two separate functions.

watchexp made it into quantize(), probably because people thought there is
a need for unlimited rescaling. This may be true, but I'd really prefer to
expose rescale() as the unlimited version then.

While it's unusual to just drop an API without deprecation, I think it's OK
in this instance: Virtually all decimal code I saw needs to be cleaned up
anyway because it uses tons of underscore methods from decimal.py.

The only thing that worries me is that there might be code which *really*
needs unlimited rescaling. Such code could of course also use a temporary
context.

So I propose this: Deprecate watchexp and leave it in the Python version for
one release. The C version won't have watchexp from the start. After all,
PEP-399 allows accelerator modules to implement a subset of the functionality
of the Python version -- sometimes PEPs are a wonderful thing :).

Here's a patch deprecating watchexp.

New changeset 7db16ff9f5fd by Stefan Krah in branch 'default':
Closes bpo-10650: Deprecate the watchexp parameter of Decimal.quantize().
http://hg.python.org/cpython/rev/7db16ff9f5fd

New changeset e4ca4edee8bd by Stefan Krah in branch 'default':
Closes bpo-10650: Deprecate the watchexp parameter of Decimal.quantize().
http://hg.python.org/cpython/rev/e4ca4edee8bd

New changeset c2f827af02a2 by Stefan Krah in branch 'default':
Issue bpo-10650: Remove the non-standard 'watchexp' parameter from the
http://hg.python.org/cpython/rev/c2f827af02a2