Fileseq Python API¶
fileseq module¶
A Python library for parsing frame ranges and file sequences commonly used in VFX and Animation applications.
The MIT License (MIT)
Original work Copyright (c) 2015 Matthew Chambers
Modified work Copyright 2015 Justin Israel
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Frame Range Shorthand
Support for:
- Standard: 1-10
- Comma Delimited: 1-10,10-20
- Chunked: 1-100x5
- Filled: 1-100y5
- Staggered: 1-100:3 (1-100x3, 1-100x2, 1-100)
- Negative frame numbers: -10-100
- Subframes: 1001-1066x0.25
- Padding: #=4 padded, @=single pad
- Printf Syntax Padding: %04d=4 padded, %01d=1 padded
- Houdini Syntax Padding: $F4=4 padding, $F=1 padded
FrameSets
A FrameSet
wraps a sequence of frames in a list list container.
Iterate a FrameSet
>>> fs = FrameSet("1-5")
>>> for f in fs:
... print(f)
1
2
3
4
5
Access Frames Using Indices
>>> fs = FrameSet("1-100:8")
>>> fs[0] # First frame.
1
>>> fs[-1] # Last frame.
98
Access Frames Using Convenience Methods:
>>> fs = FrameSet("1-100:8")
>>> fs.start() # First frame.
1
>>> fs.end() # Last frame.
98
FileSequence
A FileSequence
is a container representing a filepath over a range of frames
Instantiate from string
>>> FileSequence("/foo/bar.1-10#.exr")
<FileSequence: '/foo/bar.1-10#.exr'>
Format Path for VFX Software
Using FileSequence.format Method
>>> seq = FileSequence("/foo/bar.1-10#.exr")
>>> seq.format(template='{dirname}{basename}{padding}{extension}')
'/foo/bar.#.exr'
>>> seq = FileSequence("/foo/bar.1-10#.#.exr", allow_subframes=True)
>>> seq.format(template='{dirname}{basename}{padding}{extension}')
'/foo/bar.#.#.exr'
Joining
>>> seq = FileSequence("/foo/bar.1-10#.exr")
>>> seq.setPadding('%02d')
>>> seq
<FileSequence: '/foo/bar.1-10%02d.exr'>
>>> seq.format(template='{dirname}{basename}{padding}{extension}')
'/foo/bar.%02d.exr'
Get List of File Paths
>>> seq = FileSequence("/foo/bar.1-5#.exr")
>>> list(seq)
['/foo/bar.0001.exr',
'/foo/bar.0002.exr',
'/foo/bar.0003.exr',
'/foo/bar.0004.exr',
'/foo/bar.0005.exr']
>>> [seq[idx] for idx, fr in enumerate(seq.frameSet())]
['/foo/bar.0001.exr',
'/foo/bar.0002.exr',
'/foo/bar.0003.exr',
'/foo/bar.0004.exr',
'/foo/bar.0005.exr']
Finding Sequences on Disk
Check a Directory for All Existing Sequences
>>> seqs = findSequencesOnDisk("/show/shot/renders/bty_foo/v1")
Check a Directory for One Existing Sequence
- Use a ‘@’ or ‘#’ where you might expect to use ‘*’ for a wildcard character.
- For this method, it doesn’t matter how many instances of the padding character you use, it will still find your sequence (unless enabling strict padding option).
Yes:
findSequenceOnDisk('/foo/bar.@.exr')
Yes:
findSequenceOnDisk('/foo/bar.@@@@@.exr')
No:
findSequenceOnDisk('/foo/bar.*.exr')
- To find subframe sequences you must explicitly opt-in
fileseq.findSequenceOnDisk('/foo/bar.#.#.exr', allow_subframes=True)
fileseq.exceptions module¶
exceptions - Exception subclasses relevant to fileseq operations.
-
exception
fileseq.exceptions.
FileSeqException
[source]¶ Bases:
exceptions.ValueError
Thrown for general exceptions handled by FileSeq.
-
exception
fileseq.exceptions.
MaxSizeException
[source]¶ Bases:
exceptions.ValueError
Thrown when a range exceeds allowable size.
-
exception
fileseq.exceptions.
ParseException
[source]¶ Bases:
fileseq.exceptions.FileSeqException
Thrown after a frame range or file sequence parse error.
fileseq.filesequence module¶
filesequence - A parsing object representing sequential files for fileseq.
-
class
fileseq.filesequence.
FileSequence
(sequence, pad_style=<PAD_STYLE: HASH4>, allow_subframes=False)[source]¶ Bases:
future.types.newobject.newobject
FileSequence
represents an ordered sequence of files.Parameters: sequence (str) – (ie: dir/path.1-100#.ext)
Returns: Return type: Raises: fileseq.exceptions.MaxSizeException
– If frame size exceedsfileseq.constants.MAX_FRAME_SIZE
-
DISK_RE
= <_sre.SRE_Pattern object>¶
-
DISK_SUB_RE
= <_sre.SRE_Pattern object>¶
-
PAD_MAP
= {'#': {<PAD_STYLE: HASH1>: 1, <PAD_STYLE: HASH4>: 4}, '@': {<PAD_STYLE: HASH1>: 1, <PAD_STYLE: HASH4>: 1}}¶
-
REVERSE_PAD_MAP
= {<PAD_STYLE: HASH1>: {1: '#'}, <PAD_STYLE: HASH4>: {1: '@', 4: '#'}}¶
-
SPLIT_RE
= <_sre.SRE_Pattern object>¶
-
SPLIT_SUB_RE
= <_sre.SRE_Pattern object>¶
-
__getitem__
(idx)[source]¶ Allows indexing and slicing into the underlying
FrameSet
When indexing, a string filepath is returns for the frame.
When slicing, a new
FileSequence
is returned. Slicing outside the range of the sequence results in an IndexErrorParameters: idx (int or slice) – the desired index Returns: Return type: str or FileSequence
Raises: IndexError
– If slice is outside the range of the sequence
-
__iter__
()[source]¶ Allow iteration over the path or paths this
FileSequence
represents.Yields: FileSequence
-
__len__
()[source]¶ The length (number of files) represented by this
FileSequence
.Returns: Return type: int
-
classmethod
conformPadding
(chars, pad_style=<PAD_STYLE: HASH4>)[source]¶ Ensure alternate input padding formats are conformed to formats defined in PAD_MAP
If chars is already a format defined in PAD_MAP, then it is returned unmodified.
- Example::
- ‘#’ -> ‘#’ ‘@@@@’ -> ‘@@@@’ ‘%04d’ -> ‘#’
Parameters: - chars (str) – input padding chars
- pad_style (.PAD_STYLE_DEFAULT or .PAD_STYLE_HASH1 or .PAD_STYLE_HASH4) – padding style
Returns: conformed padding chars
Return type: str
Raises: ValueError
– If chars contains invalid padding characters
-
copy
()[source]¶ Create a deep copy of this sequence
Returns: Return type: FileSequence
-
decimalPlaces
()[source]¶ Returns the number of decimal places to output.
Returns: Return type: int or None
-
end
()[source]¶ Returns the end frame of the sequences
FrameSet
. Will return 0 if the sequence has no frame pattern.Returns: Return type: int
-
extension
()[source]¶ Return the file extension of the sequence, including leading period.
Returns: Return type: str
-
classmethod
findSequenceOnDisk
(pattern, strictPadding=False, pad_style=<PAD_STYLE: HASH4>, allow_subframes=False)[source]¶ Search for a specific sequence on disk.
The padding characters used in the pattern are used to filter the frame values of the files on disk (if strictPadding is True).
Examples
Find sequence matching basename and extension, and a wildcard for any frame. returns bar.1.exr bar.10.exr, bar.100.exr, bar.1000.exr, inclusive
FileSequence.findSequenceOnDisk("seq/bar@@@@.exr")
Find exactly 4-padded sequence, i.e. seq/bar1-100#.exr returns only frames bar1000.exr through bar9999.exr
FileSequence.findSequenceOnDisk("seq/bar#.exr", strictPadding=True)
Parameters: - pattern (str) – the sequence pattern being searched for
- strictPadding (bool) – if True, ignore files with padding length different from pattern
- pad_style (.PAD_STYLE_DEFAULT or .PAD_STYLE_HASH1 or .PAD_STYLE_HASH4) – padding style
- allow_subframes (bool) – if True, handle subframe filenames
Returns: Return type: str
Raises: FileSeqException
– if no sequence is found on disk
-
classmethod
findSequencesInList
(paths, pad_style=<PAD_STYLE: HASH4>, allow_subframes=False)[source]¶ Returns the list of discrete sequences within paths. This does not try to determine if the files actually exist on disk, it assumes you already know that.
Parameters: - paths (list[str]) – a list of paths
- pad_style (.PAD_STYLE_DEFAULT or .PAD_STYLE_HASH1 or .PAD_STYLE_HASH4) – padding style
- allow_subframes (bool) – if True, handle subframe filenames
Returns: Return type: list
-
classmethod
findSequencesOnDisk
(pattern, include_hidden=False, strictPadding=False, pad_style=<PAD_STYLE: HASH4>, allow_subframes=False)[source]¶ Yield the sequences found in the given directory.
Examples:
FileSequence.findSequencesOnDisk('/path/to/files')
- The pattern can also specify glob-like shell wildcards including the following:
?
- 1 wildcard character*
- 1 or more wildcard character{foo,bar}
- either ‘foo’ or ‘bar’
Exact frame ranges are not considered, and padding characters are converted to wildcards (
#
or@
)Examples:
FileSequence.findSequencesOnDisk('/path/to/files/image_stereo_{left,right}.#.jpg') FileSequence.findSequencesOnDisk('/path/to/files/imag?_*_{left,right}.@@@.jpg', strictPadding=True)
Parameters: - pattern (str) – directory to scan, or pattern to filter in directory
- include_hidden (bool) – if true, show .hidden files as well
- strictPadding (bool) – if True, ignore files with padding length different from pattern
- pad_style (.PAD_STYLE_DEFAULT or .PAD_STYLE_HASH1 or .PAD_STYLE_HASH4) – padding style
- allow_subframes (bool) – if True, handle subframe filenames
Returns: Return type: list
-
format
(template='{basename}{range}{padding}{extension}')[source]¶ Return the file sequence as a formatted string according to the given template.
- Utilizes the python string format syntax. Available keys include:
- basename - the basename of the sequence.
- range - the range of the sequence
- padding - the detecting amount of padding.
- extension - the file extension of the sequence.
- start - the start frame.
- end - the end frame.
- length - the length of the frame range.
- inverted - the inverted frame range. (returns “” if none)
- dirname - the directory name.
If asking for the inverted range value, and the new inverted range exceeded
fileseq.constants.MAX_FRAME_SIZE
, aMaxSizeException
will be raised.Parameters: template (str) –
Returns: Return type: str
Raises: fileseq.exceptions.MaxSizeException
– If frame size exceeds- fileseq.constants.MAX_FRAME_SIZE`
-
frame
(frame)[source]¶ Return a path for the given frame in the sequence. Numeric values or numeric strings are treated as a frame number and padding is applied, all other values are passed though.
Examples
>>> seq = FileSequence('/foo/bar.1-10#.exr') >>> seq.frame(1) '/foo/bar.0001.exr' >>> seq.frame("#") '/foo/bar.#.exr'
Parameters: frame (int, float, decimal.Decimal or str) – the desired frame number or a char to pass through (ie. #) Returns: Return type: str
-
framePadding
()[source]¶ Return the the padding characters in the sequence.
Returns: sequence padding Return type: str
-
frameRange
()[source]¶ Returns the string formatted frame range of the sequence. Will return an empty string if the sequence has no frame pattern.
Returns: Return type: str
-
frameSet
()[source]¶ Return the
FrameSet
of the sequence if specified, otherwise None.Returns: Return type: FrameSet
or None
-
classmethod
getPaddingChars
(num, pad_style=<PAD_STYLE: HASH4>)[source]¶ Given a particular amount of padding, return the proper padding characters.
Parameters: - num (int) – required width of string with padding
- pad_style (.PAD_STYLE_DEFAULT or .PAD_STYLE_HASH1 or .PAD_STYLE_HASH4) – padding style
Returns: Return type: str
-
classmethod
getPaddingNum
(chars, pad_style=<PAD_STYLE: HASH4>)[source]¶ Given a supported group of padding characters, return the amount of padding.
Parameters: - chars (str) – a supported group of padding characters
- pad_style (.PAD_STYLE_DEFAULT or .PAD_STYLE_HASH1 or .PAD_STYLE_HASH4) – padding style
Returns: Return type: int
Raises: ValueError
– if unsupported padding character is detected
-
index
(idx)[source]¶ Return the path to the file at the given index.
Parameters: idx (int) – the desired index Returns: Return type: str
-
invertedFrameRange
()[source]¶ Returns the inverse string formatted frame range of the sequence. Will return an empty string if the sequence has no frame pattern, or the frame range includes subframes.
Returns: Return type: str Raises: fileseq.exceptions.MaxSizeException
– If new inverted range exceededfileseq.constants.MAX_FRAME_SIZE
-
padStyle
()[source]¶ Return the the padding style of the sequence. See fileseq.constants.PAD_STYLE_HASH1 and fileseq.constants.PAD_STYLE_HASH4
Returns: padding style Return type: (.PAD_STYLE_DEFAULT or .PAD_STYLE_HASH1 or .PAD_STYLE_HASH4)
-
padding
()[source]¶ Return the the padding characters in the sequence.
Returns: sequence padding Return type: str
-
setBasename
(base)[source]¶ Set a new basename for the sequence.
Parameters: base (str) – the new base name
-
setDirname
(dirname)[source]¶ Set a new directory name for the sequence.
Parameters: dirname (str) – the new directory name
-
setExtension
(ext)[source]¶ Set a new file extension for the sequence.
Note
A leading period will be added if none is provided.
Parameters: ext (str) – the new file extension
-
setExtention
(ext)[source]¶ Deprecated: use
setExtension()
.Parameters: ext (str) –
-
setFramePadding
(padding)[source]¶ Set new padding characters for the frames of the sequence. i.e. “#” or “@@@” or ‘%04d’, or an empty string to disable range formatting.
Parameters: padding (str) – sequence padding to set
-
setFrameRange
(frange)[source]¶ Set a new frame range for the sequence.
Parameters: frange (str) – a properly formatted frame range, as per FrameSet
-
setFrameSet
(frameSet)[source]¶ Set a new
FrameSet
for the sequence.Parameters: frameSet ( FrameSet
) – the newFrameSet
object
-
setPadStyle
(pad_style)[source]¶ Set new padding style for the sequence. See fileseq.constants.PAD_STYLE_HASH1 and fileseq.constants.PAD_STYLE_HASH4
Parameters: pad_style (.PAD_STYLE_DEFAULT or .PAD_STYLE_HASH1 or .PAD_STYLE_HASH4) – padding style to set
-
setPadding
(padding)[source]¶ Set new padding characters for the sequence. i.e. “#” or “@@@” or ‘%04d’, or an empty string to disable range formatting.
Parameters: padding (str) – sequence padding to set
-
setSubframePadding
(padding)[source]¶ Set new padding characters for the subframes in the sequence. i.e. “#” or “@@@”, or an empty string to disable range formatting.
Parameters: padding (str) – sequence padding to set
-
split
()[source]¶ Split the
FileSequence
into contiguous pieces and return them as a list ofFileSequence
instances.Returns: Return type: list[ FileSequence
]
-
start
()[source]¶ Returns the start frame of the sequence’s
FrameSet
. Will return 0 if the sequence has no frame pattern.Returns: Return type: int
-
subframePadding
()[source]¶ Return the the padding characters for subframes in the sequence.
Returns: sequence padding Return type: str
-
classmethod
yield_sequences_in_list
(paths, using=None, pad_style=<PAD_STYLE: HASH4>, allow_subframes=False)[source]¶ Yield the discrete sequences within paths. This does not try to determine if the files actually exist on disk, it assumes you already know that.
A template
FileSequence
object can also be provided via theusing
parameter. Given this template, the dirname, basename, and extension values will be used to extract the frame value from the paths instead of parsing each path from scratch.Examples
The
using
field can supply a template for extracting the frame component from the paths:paths = [ '/dir/file_001.0001.ext', '/dir/file_002.0001.ext', '/dir/file_003.0001.ext', ] template = FileSequence('/dir/file_#.0001.ext') seqs = FileSequence.yield_sequences_in_list(paths, using) # [<FileSequence: '/dir/file_1-3@@@.0001.ext'>]
Parameters: - paths (list[str]) – a list of paths
- using (
FileSequence
) – Optional sequence to use as template - pad_style (.PAD_STYLE_DEFAULT or .PAD_STYLE_HASH1 or .PAD_STYLE_HASH4) – padding style
- allow_subframes (bool) – if True, handle subframe filenames
Yields:
fileseq.frameset module¶
frameset - A set-like object representing a frame range for fileseq.
-
class
fileseq.frameset.
FrameSet
(frange)[source]¶ Bases:
_abcoll.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.
- Because the internal storage of a
Parameters: (str or FrameSet or collections.Iterable of str, int, float, or (frange) – 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 exceedsfileseq.constants.MAX_FRAME_SIZE
-
FRANGE_RE
= <_sre.SRE_Pattern object>¶
-
PAD_MAP
= {'#': {<PAD_STYLE: HASH1>: 1, <PAD_STYLE: HASH4>: 4}, '@': {<PAD_STYLE: HASH1>: 1, <PAD_STYLE: HASH4>: 1}}¶
-
PAD_RE
= <_sre.SRE_Pattern object>¶
-
__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)
Parameters: other ( FrameSet
) –Returns: NotImplemented
: if other fails to convert to aFrameSet
Return type: FrameSet
-
__contains__
(item)[source]¶ Check if item is a member of this
FrameSet
.Parameters: item (int) – the frame number to check for Returns: 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 aFrameSet
.Parameters: other ( FrameSet
) – Also accepts an object that can be cast to aFrameSet
Returns: NotImplemented
: if other fails to convert to aFrameSet
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 aFrameSet
.Parameters: other ( FrameSet
) – Also accepts an object that can be cast to aFrameSet
Returns: NotImplemented
: if other fails to convert to aFrameSet
Return type: bool
-
__getitem__
(index)[source]¶ Allows indexing into the ordered frames of this
FrameSet
.Parameters: index (int) – the index to retrieve Returns: 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 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
Parameters: other ( FrameSet
) – Also accepts an object that can be cast to aFrameSet
Returns: NotImplemented
: if other fails to convert to aFrameSet
Return type: bool
-
__hash__
()[source]¶ Builds the hash of this
FrameSet
for equality checking and to allow use as a dictionary key.Returns: Return type: int
-
__iter__
()[source]¶ Allows for iteration over the ordered frames of this
FrameSet
.Returns: 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
.Parameters: other ( FrameSet
) – Also accepts an object that can be cast to aFrameSet
Returns: NotImplemented
: if other fails to convert to aFrameSet
Return type: bool
-
__len__
()[source]¶ Returns the length of the ordered frames of this
FrameSet
.Returns: 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 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
Parameters: other ( FrameSet
) – Can also be an object that can be cast to aFrameSet
Returns: NotImplemented
: if other fails to convert to aFrameSet
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 aFrameSet
.Parameters: other ( FrameSet
) – Also accepts an object that can be cast to aFrameSet
Returns: NotImplemented
: if other fails to convert to aFrameSet
Return type: bool
-
__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)
Parameters: other ( FrameSet
) –Returns: NotImplemented
: if other fails to convert to aFrameSet
Return type: FrameSet
-
__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)
Parameters: other ( FrameSet
) –Returns: NotImplemented
: if other fails to convert to aFrameSet
Return type: FrameSet
-
__reversed__
()[source]¶ Allows for reversed iteration over the ordered frames of this
FrameSet
.Returns: 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)
Parameters: other ( FrameSet
) –Returns: NotImplemented
: if other fails to convert to aFrameSet
Return type: FrameSet
-
__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
).Parameters: other ( FrameSet
) –Returns: NotImplemented
: if other fails to convert to aFrameSet
Return type: FrameSet
-
__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)
Parameters: other ( FrameSet
) –Returns: NotImplemented
: if other fails to convert to aFrameSet
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__
()¶
-
__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
).Parameters: other ( FrameSet
) –Returns: NotImplemented
: if other fails to convert to aFrameSet
Return type: FrameSet
-
__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)
Parameters: other ( FrameSet
) –Returns: NotImplemented
: if other fails to convert to aFrameSet
Return type: FrameSet
-
difference
(*other)[source]¶ Returns a new
FrameSet
with elements in self but not in other.Parameters: other ( FrameSet
) – or objects that can cast toFrameSet
Returns: Return type: FrameSet
-
end
()[source]¶ The last frame in the
FrameSet
.Returns: Return type: int Raises: IndexError
– (with the emptyFrameSet
)
-
frame
(index)[source]¶ Return the frame at the given index.
Parameters: index (int) – the index to find the frame for Returns: Return type: int Raises: IndexError
– if index is out of bounds
-
frameRange
(zfill=0, decimal_places=None)[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
Returns: Return type: str
-
static
framesToFrameRange
(frames, sort=True, zfill=0, compress=False)[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
Returns: Return type: str
-
static
framesToFrameRanges
(frames, zfill=0)[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
-
frange
¶ Read-only access to the frame range used to create this
FrameSet
.Returns: Return type: frozenset
-
classmethod
from_iterable
(frames, sort=False)[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
Returns: Return type:
-
classmethod
from_range
(start, end, step=1)[source]¶ Build a
FrameSet
from given start and end frames.Parameters: Returns: Return type:
-
hasFrame
(frame)[source]¶ Check if the
FrameSet
contains the frame or subframeParameters: frame (int) – the frame number to search for Returns: Return type: bool
-
index
(frame)[source]¶ Return the index of the given frame number within the
FrameSet
.Parameters: frame (int) – the frame number to find the index for Returns: Return type: int Raises: ValueError
– if frame is not in self
-
intersection
(*other)[source]¶ Returns a new
FrameSet
with the elements common to self and other.Parameters: other ( FrameSet
) – or objects that can cast toFrameSet
Returns: Return type: FrameSet
-
invertedFrameRange
(zfill=0, decimal_places=None)[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: - 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
Returns: Return type: str
Raises:
-
isConsecutive
()[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
Returns: Return type: bool
-
classmethod
isFrameRange
(frange)[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 Returns: Return type: bool
-
is_null
¶ Read-only access to determine if the
FrameSet
is the null or emptyFrameSet
.Returns: Return type: bool
-
isdisjoint
(other)[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 aFrameSet
Return type: bool
-
issubset
(other)[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 aFrameSet
Return type: bool
-
issuperset
(other)[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 aFrameSet
Return type: bool
-
items
¶ Read-only access to the unique frames that form this
FrameSet
.Returns: Return type: frozenset
-
normalize
()[source]¶ Returns a new normalized (sorted and compacted)
FrameSet
.Returns: Return type: FrameSet
-
classmethod
padFrameRange
(frange, zfill, decimal_places=None)[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) –
Returns: Return type: str
-
start
()[source]¶ The first frame in the
FrameSet
.Returns: Return type: int Raises: IndexError
– (with the emptyFrameSet
)