PEP 303 – Extend divmod() for Multiple Divisors
- Thomas Bellman <bellman+pep-divmod at lysator.liu.se>
- Standards Track
This PEP describes an extension to the built-in
allowing it to take multiple divisors, chaining several calls to
divmod() into one.
This PEP is rejected. Most uses for chained
divmod() involve a
constant modulus (in radix conversions for example) and are more
properly coded as a loop. The example of splitting seconds
into days/hours/minutes/seconds does not generalize to months
and years; rather, the whole use case is handled more flexibly and
robustly by date and time modules. The other use cases mentioned
in the PEP are somewhat rare in real code. The proposal is also
problematic in terms of clarity and obviousness. In the examples,
it is not immediately clear that the argument order is correct or
that the target tuple is of the right length. Users from other
languages are more likely to understand the standard two argument
form without having to re-read the documentation. See python-dev
discussion on 17 June 2005 .
divmod() function would be changed to accept multiple
divisors, changing its signature from
divmod(dividend, divisor) to
divmod(dividend, *divisors). The dividend is divided by the last
divisor, giving a quotient and a remainder. The quotient is then
divided by the second to last divisor, giving a new quotient and
remainder. This is repeated until all divisors have been used,
divmod() then returns a tuple consisting of the quotient from
the last step, and the remainders from all the steps.
A Python implementation of the new
divmod() behaviour could look
def divmod(dividend, *divisors): modulos = () q = dividend while divisors: q, r = q.__divmod__(divisors[-1]) modulos = (r,) + modulos divisors = divisors[:-1] return (q,) + modulos
Occasionally one wants to perform a chain of
divmod() on the quotient from the previous step, with
varying divisors. The most common case is probably converting a
number of seconds into weeks, days, hours, minutes and seconds.
This would today be written as:
def secs_to_wdhms(seconds): m, s = divmod(seconds, 60) h, m = divmod(m, 60) d, h = divmod(h, 24) w, d = divmod(d, 7) return (w, d, h, m, s)
This is tedious and easy to get wrong each time you need it.
If instead the
divmod() built-in is changed according the proposal,
the code for converting seconds to weeks, days, hours, minutes and
seconds then become
def secs_to_wdhms(seconds): w, d, h, m, s = divmod(seconds, 7, 24, 60, 60) return (w, d, h, m, s)
which is easier to type, easier to type correctly, and easier to read.
Other applications are:
- Astronomical angles (declination is measured in degrees, minutes and seconds, right ascension is measured in hours, minutes and seconds).
- Old British currency (1 pound = 20 shilling, 1 shilling = 12 pence).
- Anglo-Saxon length units: 1 mile = 1760 yards, 1 yard = 3 feet, 1 foot = 12 inches.
- Anglo-Saxon weight units: 1 long ton = 160 stone, 1 stone = 14 pounds, 1 pound = 16 ounce, 1 ounce = 16 dram.
- British volumes: 1 gallon = 4 quart, 1 quart = 2 pint, 1 pint = 20 fluid ounces.
The idea comes from APL, which has an operator that does this. (I don’t remember what the operator looks like, and it would probably be impossible to render in ASCII anyway.)
The APL operator takes a list as its second operand, while this
PEP proposes that each divisor should be a separate argument to
divmod() function. This is mainly because it is expected that
the most common uses will have the divisors as constants right in
the call (as the 7, 24, 60, 60 above), and adding a set of
parentheses or brackets would just clutter the call.
Requiring an explicit sequence as the second argument to
would seriously break backwards compatibility. Making
check its second argument for being a sequence is deemed to be too
ugly to contemplate. And in the case where one does have a
sequence that is computed other-where, it is easy enough to write
divmod(x, *divs) instead.
Requiring at least one divisor, i.e rejecting
divmod(x), has been
considered, but no good reason to do so has come to mind, and is
thus allowed in the name of generality.
divmod() with no divisors should still return a tuple (of
one element). Code that calls
divmod() with a varying number of
divisors, and thus gets a return value with an “unknown” number of
elements, would otherwise have to special case that case. Code
that knows it is calling
divmod() with no divisors is considered
to be too silly to warrant a special case.
Processing the divisors in the other direction, i.e dividing with the first divisor first, instead of dividing with the last divisor first, has been considered. However, the result comes with the most significant part first and the least significant part last (think of the chained divmod as a way of splitting a number into “digits”, with varying weights), and it is reasonable to specify the divisors (weights) in the same order as the result.
The inverse operation:
def inverse_divmod(seq, *factors): product = seq for x, y in zip(factors, seq[1:]): product = product * x + y return product
could also be useful. However, writing
seconds = (((((w * 7) + d) * 24 + h) * 60 + m) * 60 + s)
is less cumbersome both to write and to read than the chained divmods. It is therefore deemed to be less important, and its introduction can be deferred to its own PEP. Also, such a function needs a good name, and the PEP author has not managed to come up with one yet.
divmod("spam") does not raise an error, despite strings
supporting neither division nor modulo. However, unless we know
the other object too, we can’t determine whether
work or not, and thus it seems silly to forbid it.
Any module that replaces the
divmod() function in the
module, may cause other modules using the new syntax to break. It
is expected that this is very uncommon.
Code that expects a
TypeError exception when calling
anything but two arguments will break. This is also expected to
be very uncommon.
No other issues regarding backwards compatibility are known.
Not finished yet, but it seems a rather straightforward
new implementation of the function
This document has been placed in the public domain.
Last modified: 2023-09-09 17:39:29 GMT