API Reference

In addition to the methods explicitly documented here, intspan attempts to implement the complete list of set methods.

class intspan.intspan(initial=None)

A set of integers, expressed as an ordered sequence of spans. Because intspan('1-3,14,29,92-97') is better than [1, 2, 3, 14, 29, 92, 93, 94, 95, 96, 97].

__init__(initial=None)

Construct a new intspan.

Parameters:initial (iterable|str) – Optional initial list of items.
Returns:the intspan
Return type:intspan
__ior__(items)

Add multiple items.

Parameters:items (iterable|str) – Items to add. May be an intspan-style string.
__iter__()

Iterate in ascending order.

__repr__()

Return the representation.

__str__()

Return the stringification.

add(items)

Add items.

Parameters:items (iterable|str) – Items to add. May be an intspan-style string.
complement(low=None, high=None)

Return the complement of the given intspan–that is, all of the ‘missing’ elements between its minimum and missing values. Optionally allows the universe set to be manually specified.

Parameters:
  • low (int) – Low bound of universe to complement against.
  • high (int) – High bound of universe to complement against.
Returns:

the complement set

Return type:

intspan

Raises:

ValueError – if the set is empty (thus the compelement is infinite)

copy()

Return a new set with the same members.

discard(items)

Discard items.

Parameters:items (iterable|str) – Items to remove. May be an intspan-style string.
classmethod from_range(low, high)

Construct an intspan from the low value to the high value, inclusive. I.e., closed range, not the more typical Python half-open range.

Parameters:
  • low (int) – Low bound of set to construct.
  • high (int) – High bound of set to construct.
Returns:

New intspan low-high.

Return type:

intspan

classmethod from_ranges(ranges)

Construct an intspan from a sequence of (low, high) value sequences (lists or tuples, say). Note that these values are inclusive, closed ranges, not the more typical Python half-open ranges.

Parameters:ranges (list) – List of closed/inclusive ranges, each a tuple.
Returns:intspan combining the ranges
Return type:intspan
pop()

Remove and return an arbitrary element; raises KeyError if empty.

Returns:Arbitrary member of the set (which is removed)
Return type:int
Raises:KeyError – If the set is empty.
ranges()

Return a list of the set’s contiguous (inclusive) ranges.

Returns:List of all contained ranges.
Return type:list
universe(low=None, high=None)

Return the “universe” or “covering set” of the given intspan–that is, all of the integers between its minimum and missing values. Optionally allows the bounds of the universe set to be manually specified.

Parameters:
  • low (int) – Low bound of universe.
  • high (int) – High bound of universe.
Returns:

the universe or covering set

Return type:

intspan

update(items)

Add multiple items.

Parameters:items (iterable|str) – Items to add. May be an intspan-style string.
intspan.spanlist(spec=None, chunkre=<_sre.SRE_Pattern object at 0x1946980>)

Given a string specification like the ones given to intspan, return a list of the included items, in the same item given. Thus, spanlist("3,1-4") yields [3, 1, 2, 4]. Experimental partial implementation of ability to have ordered intspans.

class intspan.intspanlist(initial=None, universe=None)

An ordered version of intspan. Is to list what intspan is to set, except that it is somewhat set-like, in that items are not intended to be repeated. Works fine as an immutable data structure. Still some issues if one mutates an instance. Not terrible problems, but the set-like nature where there is only one entry for each included integer may be broken.

__init__(initial=None, universe=None)

Construct a new intspanlist

Parameters:initial (iterable|str) – Optional initial list of items.
Returns:the intspanlist
Return type:intspanlist
__repr__()

Return the representation.

__str__()

Return the stringification.

__weakref__

list of weak references to the object (if defined)

append(item)

Add to the end of the intspanlist

Parameters:item (int) – Item to add
complement(low=None, high=None)

Return the complement of the given intspanlist–that is, all of the ‘missing’ elements between its minimum and missing values. Optionally allows the universe set to be manually specified.

Parameters:
  • low (int) – Low bound of universe to complement against.
  • high (int) – High bound of universe to complement against.
Returns:

the complement set

Return type:

intspanlist

Raises:

ValueError – if the set is empty (thus the compelement is infinite)

copy()

Return a copy of the intspanlist.

extend(items)

Add a collection to the end of the intspanlist

Parameters:items (iterable) – integers to add
classmethod from_range(low, high)

Construct an intspanlist from the low value to the high value, inclusive. I.e., closed range, not the more typical Python half-open range.

Parameters:
  • low (int) – Low bound.
  • high (int) – High bound.
Returns:

New intspanlist low-high.

Return type:

intspanlist

classmethod from_ranges(ranges)

Construct an intspanlist from a sequence of (low, high) value sequences (lists or tuples, say). Note that these values are inclusive, closed ranges, not the more typical Python half-open ranges.

Parameters:ranges (list) – List of closed/inclusive ranges, each a tuple.
Returns:intspanlist combining the ranges
Return type:intspanlist
ranges()

Return a list of the set’s contiguous (inclusive) ranges.

therest_update(universe, inplace=True)

If the receiving intspanlist contains a TheRest marker, replace it with the contents of the universe. Generally done in situ, but if value of inplace kwarg false, returns an edited copy.