== A Python length gotcha

Python calls the ((__len__)) method on your objects to implement
_len()_, and in a few other situations (for example, as one way of
iterating through the elements of a sequence-like
object). Surprisingly, there's an under-documented restriction on what
your ((__len__)) can return: objects can't be larger than
_sys.maxint_.

In fact, it's stricter than that: your ((__len__)) method must return
a literal integer. You cannot return a Python 'long', even if the long
is less than _sys.maxint_. (This is arguably a bug and may be fixed in
future versions of Python, since it's a wart in the int/long
unification.)

If you return a non-int, including something larger than _sys.maxint_,
you'll get a TypeError from _len()_ (with helpful explanatory text, at
least).

It's impossible to hit this with ordinary container objects, since you
can't really create that many objects. However, you can run into this
if you have container classes that use some efficient internal
encoding.  In my case it was a class representing sets of IP address
ranges (built on top of a class to do efficient sets of (positive)
integer ranges). I decided that the right definition of 'length' was
'how many IP addresses are in this set', and then discovered that IP
addresses had to be stored as longs, not ints, which caused me to hit
both aspects of the problem at once.

I don't really have a good workaround. My number range sets class
uses:

>  def len(self):
>    ....
>  def __len__(self):
>    return int(self.len()))

Then I tell people to use _rset.len()_ instead of _len(rset)_,
and if they still use _len()_ it might still work.

=== Sidebar: _xrange()_, the other thing that cares

As I found out when writing my iterator for the number sets classes
(it returns every number in the set, one by one), _xrange()_ also
requires its arguments to be less than _sys.maxint_ (even if the span
would be smaller than _sys.maxint_).

This forced me to write a rare explicit iterating loop in Python and
led to a certain amount of muttering.