Fileseq Python API¶
fileseq module¶
fileseq.exceptions module¶
exceptions - Exception subclasses relevant to fileseq operations.
- exception fileseq.exceptions.FileSeqException[source]¶
Bases:
ValueError
Thrown for general exceptions handled by FileSeq.
- exception fileseq.exceptions.MaxSizeException[source]¶
Bases:
ValueError
Thrown when a range exceeds allowable size.
- exception fileseq.exceptions.ParseException[source]¶
Bases:
FileSeqException
Thrown after a frame range or file sequence parse error.
fileseq.filesequence module¶
fileseq.frameset module¶
frameset - A set-like object representing a frame range for fileseq.
- class fileseq.frameset.FrameSet(*args, **kwargs)[source]¶
Bases:
Set
A
FrameSet
is an immutable representation of the ordered, unique set of frames in a given frame range.- The frame range can be expressed in the following ways:
1-5
1-5,10-20
1-100x5 (every fifth frame)
1-100y5 (opposite of above, fills in missing frames)
1-100:4 (same as 1-100x4,1-100x3,1-100x2,1-100)
1-2x0.333333 (subframes)
A
FrameSet
is effectively an ordered frozenset, with FrameSet-returning versions of frozenset methods:>>> FrameSet('1-5').union(FrameSet('5-10')) FrameSet("1-10") >>> FrameSet('1-5').intersection(FrameSet('5-10')) FrameSet("5")
Because a FrameSet is hashable, it can be used as the key to a dictionary:
>>> d = {FrameSet("1-20"): 'good'}
A FrameSet can be created from an iterable of frame numbers, and will construct an appropriate string representation:
>>> FrameSet([1,2,3,4,5]).frange '1-5' >>> FrameSet([0, '0.1429', '0.2857', '0.4286', '0.5714', '0.7143', '0.8571', 1]).frange '0-1x0.142857'
- Caveats:
Because the internal storage of a
FrameSet
contains the discreet values of the entire range, an exception will be thrown if the range exceeds a large reasonable limit, which could lead to huge memory allocations or memory failures. Seefileseq.constants.MAX_FRAME_SIZE
.All frozenset operations return a normalized
FrameSet
: internal frames are in numerically increasing order.Equality is based on the contents and order, NOT the frame range string (there are a finite, but potentially extremely large, number of strings that can represent any given range, only a “best guess” can be made).
Human-created frame ranges (ie 1-100x5) will be reduced to the actual internal frames (ie 1-96x5).
The “null”
Frameset
(FrameSet('')
) is now a valid thing to create, it is required by set operations, but may cause confusion as both its start and end methods will raise IndexError. Theis_null()
property allows you to guard against this.
- Parameters:
str (frange (str or FrameSet or collections.Iterable of) – decimal.Decimal): the frame range as a string (ie “1-100x5”) or iterable of frame numbers.
int – decimal.Decimal): the frame range as a string (ie “1-100x5”) or iterable of frame numbers.
float – decimal.Decimal): the frame range as a string (ie “1-100x5”) or iterable of frame numbers.
or – decimal.Decimal): the frame range as a string (ie “1-100x5”) or iterable of frame numbers.
- Raises:
.ParseException – if the frame range (or a portion of it) could not be parsed.
fileseq.exceptions.MaxSizeException – if the range exceeds
fileseq.constants.MAX_FRAME_SIZE
- FRANGE_RE = re.compile('\n \\A\n (-?\\d+(?:\\.\\d+)?) # start frame\n (?: # optional range\n - # range delimiter\n (-?\\d+(?:\\.\\d+)?) # end , re.VERBOSE)¶
- PAD_MAP = {'#': {<PAD_STYLE: HASH1>: 1, <PAD_STYLE: HASH4>: 4}, '@': {<PAD_STYLE: HASH1>: 1, <PAD_STYLE: HASH4>: 1}}¶
- PAD_RE = re.compile('\n (-?)(\\d+(?:\\.\\d+)?) # start frame\n (?: # optional range\n (-) # range delimiter\n (-?)(\\d+(?:\\.\\d+)?) # end frame\n (?, re.VERBOSE)¶
- __and__(other)[source]¶
Overloads the
&
operator. Returns a newFrameSet
that holds only the frames self and other have in common.Note
The order of operations is irrelevant:
(self & other) == (other & self)
- __eq__(other)[source]¶
Check if self == other via a comparison of the hash of their contents. If other is not a
FrameSet
, but is a set, frozenset, or is iterable, it will be cast to aFrameSet
.
- __ge__(other)[source]¶
Check if self >= other via a comparison of the contents. If other is not a
FrameSet
, but is a set, frozenset, or is iterable, it will be cast to aFrameSet
.
- __getitem__(index)[source]¶
Allows indexing into the ordered frames of this
FrameSet
.- Parameters:
index (int) – the index to retrieve
- Return type:
- Raises:
IndexError – if index is out of bounds
- __getstate__()[source]¶
Allows for serialization to a pickled
FrameSet
.- Returns:
(frame range string, )
- Return type:
- __gt__(other)[source]¶
Check if self > other via a comparison of the contents. If other is not a
FrameSet
, but is a set, frozenset, or is iterable, it will be cast to aFrameSet
.Note
A
FrameSet
is greater than other if the set of its contents are greater, OR if the contents are equal but the order is greater.>>> FrameSet("1-5") > FrameSet("5-1") False
- __hash__()[source]¶
Builds the hash of this
FrameSet
for equality checking and to allow use as a dictionary key.- Return type:
- __iter__()[source]¶
Allows for iteration over the ordered frames of this
FrameSet
.- Return type:
generator
- __le__(other)[source]¶
Check if self <= other via a comparison of the contents. If other is not a
FrameSet
, but is a set, frozenset, or is iterable, it will be cast to aFrameSet
.
- __lt__(other)[source]¶
Check if self < other via a comparison of the contents. If other is not a
FrameSet
, but is a set, frozenset, or is iterable, it will be cast to aFrameSet
.Note
A
FrameSet
is less than other if the set of its contents are less, OR if the contents are equal but the order of the items is less.>>> FrameSet("1-5") < FrameSet("5-1") True
- __ne__(other)[source]¶
Check if self != other via a comparison of the hash of their contents. If other is not a
FrameSet
, but is a set, frozenset, or is iterable, it will be cast to aFrameSet
.
- __or__(other)[source]¶
Overloads the
|
operator. Returns a newFrameSet
that holds all the frames in self, other, or both.Note
The order of operations is irrelevant:
(self | other) == (other | self)
- __rand__(other)¶
Overloads the
&
operator. Returns a newFrameSet
that holds only the frames self and other have in common.Note
The order of operations is irrelevant:
(self & other) == (other & self)
- __reversed__()[source]¶
Allows for reversed iteration over the ordered frames of this
FrameSet
.- Return type:
generator
- __ror__(other)¶
Overloads the
|
operator. Returns a newFrameSet
that holds all the frames in self, other, or both.Note
The order of operations is irrelevant:
(self | other) == (other | self)
- __rsub__(other)[source]¶
Overloads the
-
operator. Returns a newFrameSet
that holds only the frames of other that are not in self.Note
This is for right-hand subtraction (
other - self
).
- __rxor__(other)¶
Overloads the
^
operator. Returns a newFrameSet
that holds all the frames in self or other but not both.Note
The order of operations is irrelevant:
(self ^ other) == (other ^ self)
- __setstate__(state)[source]¶
Allows for de-serialization from a pickled
FrameSet
.- Parameters:
state (tuple or str or dict) – A string/dict can be used for backwards compatibility
- Raises:
ValueError – if state is not an appropriate type
- __sub__(other)[source]¶
Overloads the
-
operator. Returns a newFrameSet
that holds only the frames of self that are not in other.Note
This is for left-hand subtraction (
self - other
).
- __xor__(other)[source]¶
Overloads the
^
operator. Returns a newFrameSet
that holds all the frames in self or other but not both.Note
The order of operations is irrelevant:
(self ^ other) == (other ^ self)
- batches(batch_size: int, frames: bool = False) Iterator [source]¶
Returns a generator that yields sub-batches of frames, up to
batch_size
. Ifframes=False
, each batch is a newFrameSet
subrange. Ifframes=True
, each batch is an islice generator object of the sub-range.
- difference(*other) FrameSet [source]¶
Returns a new
FrameSet
with elements in self but not in other.
- end() int [source]¶
The last frame in the
FrameSet
.- Return type:
- Raises:
IndexError – (with the empty
FrameSet
)
- frame(index: int) int [source]¶
Return the frame at the given index.
- Parameters:
index (int) – the index to find the frame for
- Return type:
- Raises:
IndexError – if index is out of bounds
- frameRange(zfill: int = 0, decimal_places: int | None = None) str [source]¶
Return the frame range used to create this
FrameSet
, padded if desired.Examples
>>> FrameSet('1-100').frameRange() '1-100' >>> FrameSet('1-100').frameRange(5) '00001-00100' >>> FrameSet('1-100').frameRange(0, 1) '1.0-100.0' >>> FrameSet('1.0-100.0').frameRange() '1.0-100.0'
- static framesToFrameRange(frames: Iterable, sort: bool = True, zfill: int = 0, compress: bool = False) str [source]¶
Converts an iterator of frames into a frame range string.
- static framesToFrameRanges(frames: Iterable, zfill: int = 0) Iterator[str] [source]¶
Converts a sequence of frames to a series of padded frame range strings.
- Parameters:
frames (collections.Iterable) – sequence of frames to process
zfill (int) – width for zero padding
- Yields:
str
- property frange: str¶
Read-only access to the frame range used to create this
FrameSet
.- Return type:
- classmethod from_iterable(frames: Iterable[int], sort: bool = False) FrameSet [source]¶
Build a
FrameSet
from an iterable of frames.
- classmethod from_range(start: int, end: int, step: int = 1) FrameSet [source]¶
Build a
FrameSet
from given start and end frames (inclusive).
- index(frame: int) int [source]¶
Return the index of the given frame number within the
FrameSet
.- Parameters:
frame (int) – the frame number to find the index for
- Return type:
- Raises:
ValueError – if frame is not in self
- intersection(*other) FrameSet [source]¶
Returns a new
FrameSet
with the elements common to self and other.
- invertedFrameRange(zfill: int = 0, decimal_places: int | None = None) str [source]¶
Return the inverse of the
FrameSet
‘s frame range, padded if desired. The inverse is every frame within the full extent of the range.Examples
>>> FrameSet('1-100x2').invertedFrameRange() '2-98x2' >>> FrameSet('1-100x2').invertedFrameRange(5) '00002-00098x2'
If the inverted frame size exceeds
fileseq.constants.MAX_FRAME_SIZE
, aMaxSizeException
will be raised.- Parameters:
- Return type:
- Raises:
- isConsecutive() bool [source]¶
Return whether the frame range represents consecutive integers, as opposed to having a stepping >= 2
Examples
>>> FrameSet('1-100').isConsecutive() True >>> FrameSet('1-100x2').isConsecutive() False >>> FrameSet('1-50,60-100').isConsecutive() False
- Return type:
- classmethod isFrameRange(frange: str) bool [source]¶
Return True if the given string is a frame range. Any padding characters, such as ‘#’ and ‘@’ are ignored.
- property is_null: bool¶
Read-only access to determine if the
FrameSet
is the null or emptyFrameSet
.- Return type:
- isdisjoint(other) bool | NotImplemented [source]¶
Check if the contents of :class:self has no common intersection with the contents of :class:other.
- issubset(other) bool | NotImplemented [source]¶
Check if the contents of self is a subset of the contents of other.
- issuperset(other) bool | NotImplemented [source]¶
Check if the contents of self is a superset of the contents of other.
- property items: frozenset[int]¶
Read-only access to the unique frames that form this
FrameSet
.- Return type:
- normalize() FrameSet [source]¶
Returns a new normalized (sorted and compacted)
FrameSet
.- Return type:
- property order: tuple[int, ...]¶
Read-only access to the ordered frames that form this
FrameSet
.- Return type:
- classmethod padFrameRange(frange: str, zfill: int, decimal_places: int | None = None) str [source]¶
Return the zero-padded version of the frame range string.
- start() int [source]¶
The first frame in the
FrameSet
.- Return type:
- Raises:
IndexError – (with the empty
FrameSet
)
fileseq.utils module¶
utils - General tools of use to fileseq operations.
- fileseq.utils.asString(obj)[source]¶
Ensure an object is either explicitly str or unicode and not some derived type that can change semantics.
If the object is unicode, return unicode. Otherwise, return the string conversion of the object.
- Parameters:
obj – Object to return as str or unicode
- Return type:
str or unicode
- fileseq.utils.batchFrames(start, stop, batch_size)[source]¶
Returns a generator that yields batches of frames from start to stop, inclusive. Each batch value is a
range
generator object, also providing start, stop, and step properties. The last batch frame length may be smaller if the batches cannot be divided evenly.start value is allowed to be greater than stop value, to generate decreasing frame values.
- fileseq.utils.batchIterable(it, batch_size)[source]¶
Returns a generator that yields batches of items returned by the given iterable. The last batch frame length may be smaller if the batches cannot be divided evenly.
- Parameters:
it (iterable) – An iterable from which to yield batches of values
batch_size (int) – max size of each batch
- Yields:
iterable – a subset of batched items
- fileseq.utils.lenRange(start, stop, step=1)[source]¶
Get the length of values for a given range, exclusive of the stop
- fileseq.utils.normalizeFrame(frame)[source]¶
Convert a frame number to the most appropriate type - the most compact type that doesn’t affect precision, for example numbers that convert exactly to integer values will be converted to int
- Parameters:
frame (int, float, decimal.Decimal, str) – frame number to normalize
- Return type:
frame (int, float, or decimal.Decimal)
- fileseq.utils.normalizeFrames(frames: Iterable[Any]) list [source]¶
Convert a sequence of frame numbers to the most appropriate type for the overall sequence, where all members of the result are of the same type.
- Parameters:
frames (iterable of int, float, decimal.Decimal, or str) – frame numbers to normalize
- Return type:
frames (iterable of int, float, or decimal.Decimal)
- fileseq.utils.pad(number, width=0, decimal_places=None)[source]¶
Return the zero-padded string of a given number.
- fileseq.utils.quantize(number, decimal_places, rounding='ROUND_HALF_EVEN')[source]¶
Round a decimal value to given number of decimal places
- Parameters:
number (decimal.Decimal) – Decimal number to round
decimal_places (int) – Number of decimal places in return value
rounding (str) – decimal.Decimal rounding mode. See rounding argument of https://docs.python.org/2/library/decimal.html#decimal.Context
- Return type:
- fileseq.utils.unique(seen, *iterables)[source]¶
Get the unique items in iterables while preserving order. Note that this mutates the seen set provided only when the returned generator is used.
- Parameters:
seen (set) – either an empty set, or the set of things already seen
*iterables – one or more iterable lists to chain together
- Return type:
generator
- fileseq.utils.xfrange(start, stop, step=1, maxSize=-1)[source]¶
Returns a generator that yields the frames from start to stop, inclusive. In other words it adds or subtracts a frame, as necessary, to return the stop value as well, if the stepped range would touch that value.
- Parameters:
- Return type:
generator
- Raises:
fileseq.exceptions.MaxSizeException – if size is exceeded
- class fileseq.utils.xrange2(start, stop=None, step=1)[source]¶
Bases:
object
An itertools-based replacement for xrange which does not exhibit the OverflowError issue on some platforms, when a value exceeds a C long size.
Provides the features of an islice, with the added support for checking the length of the range.
- property start¶
- property step¶
- property stop¶