intspan / README.rst

Subset of set designed to conveniently hold sets of integers. It creates them from, and displays them as, integer spans (e.g. 1-3,14,29,92-97). When iterating over an intspan, iteration is ordered.

The main draw is that this provides a convenient way to specify ranges--for example, ranges of rows to be processed in a spreadsheet.


from intspan import intspan

s = intspan('1-3,14,29,92-97')
print s




for n in intspan('1-3,5'):
    print n                 # Python 2




intspan piggybacks Python's set, so it stores every integer individually. Unlike Perl's Set::IntSpan it is not optimized for long contiguous runs. For sets of several hundred or thousand members, you will probably never notice the difference.

On the other hand, if you're dealing with large sets (e.g. with 10,000 or more elements), or doing lots of set operations on them (e.g. union, intersection), a data structure based on lists of ranges, run length encoding, or Judy arrays would probably perform / scale better.


There are several generally available modules you might want to consider as alternatives or supplements. None of them provide (AFAIK) the convenient integer span specification that intspan does, but they have other virtues:

  • cowboy provides generalized ranges and multi-ranges. Bonus points for the package name: "It works on ranges."
  • rangeset is a generalized range set module. It also supports infinite ranges.
  • judy a Python wrapper around Judy arrays that are implemented in C. No docs or tests to speak of.


  • Some set operations such as update(), add(), discard(), and remove() take integer span strings as arguments. In some cases this changes a method that took one item into one that takes multiple. Not all set operations have been so extended.
  • String representation based on Jeff Mercado's concise answer to this StackOverflow question. Thank you, Jeff!
  • Automated multi-version testing managed with the wonderful pytest and tox. Successfully packaged for, and tested against, all late-model verions of Python: 2.6, 2.7, 3.2, and 3.3, as well as PyPy 1.9 (based on 2.7.2).
  • The author, Jonathan Eunice or @jeunice on Twitter welcomes your comments and suggestions.


To install the latest version:

pip install -U intspan

To easy_install under a specific Python version (3.3 in this example):

python3.3 -m easy_install --upgrade intspan

(You may need to prefix these with "sudo " to authorize installation.)