SmartRange: Ranges done simply and smartly¶
SmartRange is a simple module designed to make working with ranges not suck.
It provides a single class that represents a list of range
objects.
SmartRange Class¶
- class smart_range.SmartRange(range_str: str, *, min_val: Optional[int] = None, max_val: Optional[int] = None)¶
The class that represents a range of values. Input consists of a string containing the range.
A range string is a comma-separated list of range items. There are 5 types of range items supported by the class:
Classic range with a defined start and finish. Example:
1-5
Warning
Range items cannot have a negative difference between the start and finish values.
Range with a defined start and an undefined finish. This requires the
max_val
parameter to be supplied to the__init__()
method. This type of range can only show up once at the end of the range string. Example:1-
Range with an undefined start and a defined finish. If this item is the first range in the range string, it requires the
min_val
parameter to be supplied to the__init__()
method. Otherwise, it will assume that the starting value is one more than the previous range item.Example at the start of the range string with a defined
min_val
parameter:-5
-><min_val>-5
Example where the range string is
1-5,-8
->1-5,6-8
A plus symbol and a number. This will indicate a range where the end of the previous range plus one is the starting number, and the end of the range is the starting number plus the provided number minus one. If specified at the beginning of the range string, it requires the
min_val
parameter to be supplied to the__init__()
method.Example at the start of the range string with a defined
min_val
parameter:+5
-><min_val> - <min_val+5>
Example where the range string is
1-5,+8
->1-5,6-13
A singular dash, indicating a range with an undefined start and an undefined finish. This requires the
min_val
and themax_val
parameter to be supplied to the__init__()
method. Additionally, this item can only show up once at the end of a range string. Example:-
- __init__(range_str: str, *, min_val: Optional[int] = None, max_val: Optional[int] = None)¶
Create a new
SmartRange
object.- Parameters
range_str (str) – The input range string.
min_val (Optional[int]) – The minimum value of the range. If not supplied, range items #2 and #4 cannot be supplied at the beginning of the range string.
max_val (Optional[int]) –
The maximum value of the range. If not supplied, range item #3 cannot be supplied at the end of the range string.
Warning
If a
max_val
is supplied, no item in the range string can have an end value greater than the supplied maximum value.
- Raises
NoMinimumValueError – If a type 2 or 4 range item is used at the beginning of the range string and no
min_val
is supplied.NoMaximumValueError – If a type 3 range item is used at the end of the range string and no
max_val
is supplied.NegativeRangeError – If a range item has a negative difference between the start and finish values.
ExceedsMaximumValueError – If
max_val
is provided and a range item has an end value greater thanmax_val
.
- __iter__() Generator[int, None, None] ¶
Returns a generator containing all the numbers in the smart range.
Note
In order to iterate over the list of range objects, use the
ranges
attribute, such as:for range_obj in smart_range.ranges: print(range_obj.start, range_obj.stop)
- __weakref__¶
list of weak references to the object (if defined)
- classmethod from_range_list(range_list: List[range]) smart_range.smart_range.SmartRange ¶
Create a new
SmartRange
object from a list ofrange
s.Note
range
objects exclude thestop
parameter, sorange(1, 2)
is not the same as the range string1-2
. The range object for1-2
isrange(1, 3)
.Warning
When using this method, none of the checks for
__init__()
are performed. In order to process these checks, this workaround can be used:smart_range = SmartRange.from_range_list([range(1, 11), range(11, 16]) validated_range = SmartRange(str(smart_range))
- ranges: List[range]¶
The list of
range
s. Can be externally modified to add, change, or remove ranges.Warning
Adding a range out of order may result in unordered output from
__iter__()
.
Exceptions¶
- exception smart_range.exceptions.ExceedsMaximumValueError(start: int, end: int, max_value: int)¶
Raised when a value goes past the maximum.
- exception smart_range.exceptions.NegativeRangeError(start: int, end: int)¶
Raised when a range is specified that is negative.
- exception smart_range.exceptions.NoMaximumValueError(start: int)¶
Raised when a range is specified that assumes a maximum value but none if specified.
- exception smart_range.exceptions.NoMinimumValueError(end: int)¶
Raised when a range is specified that assumes a minimum value but none if specified.
- exception smart_range.exceptions.NoValueExpectedError¶
Raised when a value is expected but none is provided.
- exception smart_range.exceptions.RangeError¶
Raised when a value is invalid.