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:
  1. 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. See fileseq.constants.MAX_FRAME_SIZE.

  2. All frozenset operations return a normalized FrameSet: internal frames are in numerically increasing order.

  3. 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).

  4. Human-created frame ranges (ie 1-100x5) will be reduced to the actual internal frames (ie 1-96x5).

  5. 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. The is_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 new FrameSet that holds only the frames self and other have in common.

Note

The order of operations is irrelevant: (self & other) == (other & self)

Parameters:

other (FrameSet) –

Returns:

NotImplemented: if other fails to convert to a FrameSet

Return type:

FrameSet

__contains__(item)[source]

Check if item is a member of this FrameSet.

Parameters:

item (int) – the frame number to check for

Return type:

bool

__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 a FrameSet.

Parameters:

other (FrameSet) – Also accepts an object that can be cast to a FrameSet

Returns:

NotImplemented: if other fails to convert to a FrameSet

Return type:

bool

__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 a FrameSet.

Parameters:

other (FrameSet) – Also accepts an object that can be cast to a FrameSet

Returns:

NotImplemented: if other fails to convert to a FrameSet

Return type:

bool

__getitem__(index)[source]

Allows indexing into the ordered frames of this FrameSet.

Parameters:

index (int) – the index to retrieve

Return type:

int

Raises:

IndexError – if index is out of bounds

__getstate__()[source]

Allows for serialization to a pickled FrameSet.

Returns:

(frame range string, )

Return type:

tuple

__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 a FrameSet.

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.

Same contents, but (1,2,3,4,5) sorts below (5,4,3,2,1)
>>> FrameSet("1-5") > FrameSet("5-1")
False
Parameters:

other (FrameSet) – Also accepts an object that can be cast to a FrameSet

Returns:

NotImplemented: if other fails to convert to a FrameSet

Return type:

bool

__hash__()[source]

Builds the hash of this FrameSet for equality checking and to allow use as a dictionary key.

Return type:

int

__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 a FrameSet.

Parameters:

other (FrameSet) – Also accepts an object that can be cast to a FrameSet

Returns:

NotImplemented: if other fails to convert to a FrameSet

Return type:

bool

__len__()[source]

Returns the length of the ordered frames of this FrameSet.

Return type:

int

__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 a FrameSet.

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.

Same contents, but (1,2,3,4,5) sorts below (5,4,3,2,1)
>>> FrameSet("1-5") < FrameSet("5-1")
True
Parameters:

other (FrameSet) – Can also be an object that can be cast to a FrameSet

Returns:

NotImplemented: if other fails to convert to a FrameSet

Return type:

bool

__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 a FrameSet.

Parameters:

other (FrameSet) – Also accepts an object that can be cast to a FrameSet

Returns:

NotImplemented: if other fails to convert to a FrameSet

Return type:

bool

__or__(other)[source]

Overloads the | operator. Returns a new FrameSet that holds all the frames in self, other, or both.

Note

The order of operations is irrelevant: (self | other) == (other | self)

Parameters:

other (FrameSet) –

Returns:

NotImplemented: if other fails to convert to a FrameSet

Return type:

FrameSet

__rand__(other)

Overloads the & operator. Returns a new FrameSet that holds only the frames self and other have in common.

Note

The order of operations is irrelevant: (self & other) == (other & self)

Parameters:

other (FrameSet) –

Returns:

NotImplemented: if other fails to convert to a FrameSet

Return type:

FrameSet

__repr__()[source]

Returns a long-form representation of this FrameSet.

Return type:

str

__reversed__()[source]

Allows for reversed iteration over the ordered frames of this FrameSet.

Return type:

generator

__ror__(other)

Overloads the | operator. Returns a new FrameSet that holds all the frames in self, other, or both.

Note

The order of operations is irrelevant: (self | other) == (other | self)

Parameters:

other (FrameSet) –

Returns:

NotImplemented: if other fails to convert to a FrameSet

Return type:

FrameSet

__rsub__(other)[source]

Overloads the - operator. Returns a new FrameSet that holds only the frames of other that are not in self.

Note

This is for right-hand subtraction (other - self).

Parameters:

other (FrameSet) –

Returns:

NotImplemented: if other fails to convert to a FrameSet

Return type:

FrameSet

__rxor__(other)

Overloads the ^ operator. Returns a new FrameSet that holds all the frames in self or other but not both.

Note

The order of operations is irrelevant: (self ^ other) == (other ^ self)

Parameters:

other (FrameSet) –

Returns:

NotImplemented: if other fails to convert to a FrameSet

Return type:

FrameSet

__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

__str__()[source]

Returns the frame range string of this FrameSet.

Return type:

str

__sub__(other)[source]

Overloads the - operator. Returns a new FrameSet that holds only the frames of self that are not in other.

Note

This is for left-hand subtraction (self - other).

Parameters:

other (FrameSet) –

Returns:

NotImplemented: if other fails to convert to a FrameSet

Return type:

FrameSet

__xor__(other)[source]

Overloads the ^ operator. Returns a new FrameSet that holds all the frames in self or other but not both.

Note

The order of operations is irrelevant: (self ^ other) == (other ^ self)

Parameters:

other (FrameSet) –

Returns:

NotImplemented: if other fails to convert to a FrameSet

Return type:

FrameSet

batches(batch_size: int, frames: bool = False) Iterator[source]

Returns a generator that yields sub-batches of frames, up to batch_size. If frames=False, each batch is a new FrameSet subrange. If frames=True, each batch is an islice generator object of the sub-range.

Parameters:
  • batch_size (int) – max frame values in each batch

  • frames (bool) – if True, generate islice sub-ranges instead of FrameSets

Returns:

yields batches of islice or FrameSet sub-ranges

Return type:

generator

copy() FrameSet[source]

Create a deep copy of this FrameSet.

Return type:

FrameSet

difference(*other) FrameSet[source]

Returns a new FrameSet with elements in self but not in other.

Parameters:

other (FrameSet) – or objects that can cast to FrameSet

Return type:

FrameSet

end() int[source]

The last frame in the FrameSet.

Return type:

int

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:

int

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'
Parameters:
  • zfill (int) – the width to use to zero-pad the frame range string

  • decimal_places (int or None) – the number of decimal places to use in frame range string

Return type:

str

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.

Parameters:
  • frames (collections.Iterable) – sequence of frames to process

  • sort (bool) – sort the sequence before processing

  • zfill (int) – width for zero padding

  • compress (bool) – remove any duplicates before processing

Return type:

str

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:

str

classmethod from_iterable(frames: Iterable[int], sort: bool = False) FrameSet[source]

Build a FrameSet from an iterable of frames.

Parameters:
  • frames (collections.Iterable) – an iterable object containing frames as integers

  • sort (bool) – True to sort frames before creation, default is False

Return type:

FrameSet

classmethod from_range(start: int, end: int, step: int = 1) FrameSet[source]

Build a FrameSet from given start and end frames (inclusive).

Parameters:
  • start (int) – The first frame of the FrameSet.

  • end (int) – The last frame of the FrameSet.

  • step (int, optional) – Range step (default 1).

Return type:

FrameSet

hasFrame(frame: int) bool[source]

Check if the FrameSet contains the frame or subframe

Parameters:

frame (int) – the frame number to search for

Return type:

bool

hasSubFrames() bool[source]

Check if the FrameSet contains any subframes

Return type:

bool

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:

int

Raises:

ValueError – if frame is not in self

intersection(*other) FrameSet[source]

Returns a new FrameSet with the elements common to self and other.

Parameters:

other (FrameSet) – or objects that can cast to FrameSet

Return type:

FrameSet

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, a MaxSizeException will be raised.

Parameters:
  • zfill (int) – the width to use to zero-pad the frame range string

  • decimal_places (int or None) – the number of decimal places to use in frame range string

Return type:

str

Raises:

fileseq.exceptions.MaxSizeException

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:

bool

classmethod isFrameRange(frange: str) bool[source]

Return True if the given string is a frame range. Any padding characters, such as ‘#’ and ‘@’ are ignored.

Parameters:

frange (str) – a frame range to test

Return type:

bool

property is_null: bool

Read-only access to determine if the FrameSet is the null or empty FrameSet.

Return type:

bool

isdisjoint(other) bool | NotImplemented[source]

Check if the contents of :class:self has no common intersection with the contents of :class:other.

Parameters:

other (FrameSet) –

Returns:

NotImplemented: if other fails to convert to a FrameSet

Return type:

bool

issubset(other) bool | NotImplemented[source]

Check if the contents of self is a subset of the contents of other.

Parameters:

other (FrameSet) –

Returns:

NotImplemented: if other fails to convert to a FrameSet

Return type:

bool

issuperset(other) bool | NotImplemented[source]

Check if the contents of self is a superset of the contents of other.

Parameters:

other (FrameSet) –

Returns:

NotImplemented: if other fails to convert to a FrameSet

Return type:

bool

property items: frozenset[int]

Read-only access to the unique frames that form this FrameSet.

Return type:

frozenset

normalize() FrameSet[source]

Returns a new normalized (sorted and compacted) FrameSet.

Return type:

FrameSet

property order: tuple[int, ...]

Read-only access to the ordered frames that form this FrameSet.

Return type:

tuple

classmethod padFrameRange(frange: str, zfill: int, decimal_places: int | None = None) str[source]

Return the zero-padded version of the frame range string.

Parameters:
  • frange (str) – a frame range to test

  • zfill (int) –

  • decimal_places (int or None) –

Return type:

str

start() int[source]

The first frame in the FrameSet.

Return type:

int

Raises:

IndexError – (with the empty FrameSet)

symmetric_difference(other) FrameSet[source]

Returns a new FrameSet that contains all the elements in either self or other, but not both.

Parameters:

other (FrameSet) –

Return type:

FrameSet

union(*other) FrameSet[source]

Returns a new FrameSet with the elements of self and of other.

Parameters:

other (FrameSet) – or objects that can cast to FrameSet

Return type:

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.

Parameters:
  • start (int) – start frame value

  • stop (int) – stop frame value

  • batch_size (int) – max size of each batch

Yields:

range(sub_start, sub_stop)

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

Parameters:
  • start (int) –

  • stop (int) –

  • step (int) –

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.

Parameters:
  • number (str, int, float, or decimal.Decimal) – the number to pad

  • width (int) – width for zero padding the integral component

  • decimal_places (int) – number of decimal places to use in frame range

Return type:

str

fileseq.utils.quantize(number, decimal_places, rounding='ROUND_HALF_EVEN')[source]

Round a decimal value to given number of decimal places

Parameters:
Return type:

decimal.Decimal

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:
  • start (int) –

  • stop (int) –

  • step (int) – Note that the sign will be ignored

  • maxSize (int) –

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