skip to navigation
skip to content

Not Logged In

intspan 1.0.3

Sets of integers like 1,3-7,33. Inspired by Perl's Set::IntSpan

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, pop()-ing an item, or converting to a list, intspan behaves as if it were an ordered collection.

The main draw is that this provides a convenient way to specify ranges–for example, ranges of rows to be processed in a spreadsheet. It can also help you quickly identify which items were not successfully processed in a large dataset.


from intspan import intspan

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


[1, 3, 14, 29, 93, 94, 95, 96, 97]


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



Most set operations such as intersection, union, and so on are available just as they are in Python’s set. In addition, if you wish to extract the contiguous ranges:

for r in intspan('1-3,5,7-9,10,21-22,23,24').ranges():
    print r                 # Python 2


(1, 3)
(5, 5)
(7, 10)
(21, 24)

Note that these are the endpoints of closed intervals, rather than the half-open intervals Python’s range() function expects. If you want to use these with Python generators, you’ll have to increment the stop value yourself.

There is a corresponding constructor:

print intspan.from_ranges([ (4,6), (10,12) ])




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 even many thousands of members, you will probably never notice the difference.

On the other hand, if you’re doing lots of processing of large sets (e.g. with 100,000, 1M, 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 might perform / scale better.


There are several modules you might want to consider as alternatives or supplements. AFAIK, none of them provide 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 tagline: “It works on ranges.”
  • ranger is a generalized range and range set module. It supports open and closed ranges, and includes mapping objects that attach one or more objects to range sets.
  • 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.


  • Patch versions through 1.0.3 are minor bumps, with small testing and documentation improvements.
  • Version 1.0 immediately follows 0.73. Bumped to institute a cleaner “semantic versioning” scheme. Upgraded from “beta” to “production” status.
  • Version 0.73 updates testing to include the latest Python 3.4
  • Version 0.7 fixed parsing of spans including negative numbers, and added the ranges() method. As of 0.71, the from_ranges() constructor appeared.
  • Though inspired by Perl’s Set::IntSpan, that’s where the similarity stops. intspan supports only finite sets, and it follows the methods and conventions of Python’s set.
  • intspan methods and operations such as add() discard(), and >= take integer span strings, lists, and sets as arguments, changing facilities that used to take only one item into ones that take multiples, including arguments that are technically string specifications rather than proper intspan objects.
  • String representation and ranges() method based on Jeff Mercado’s concise answer to this StackOverflow question. Thank you, Jeff!
  • Automated multi-version testing managed with the wonderful pytest, pytest-cov, and tox. Successfully packaged for, and tested against, all late-model versions of Python: 2.6, 2.7, 3.2, 3.3, 3.4, 3.5a4, as well as PyPy 2.5.1 (based on 2.7.9) and PyPy3 2.4.0 (based on 3.2.5). Test line coverage ~100%.
  • 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. In environments without super-user privilges, you may want to use pip’s --user option, to install only for a single user, rather than system-wide.)

File Type Py Version Uploaded on Size
intspan-1.0.3.tar.gz (md5) Source 2015-05-13 7KB (md5) Source 2015-05-13 14KB
  • Downloads (All Versions):
  • 129 downloads in the last day
  • 614 downloads in the last week
  • 2153 downloads in the last month