API Reference¶

The documented objects on this page are exported from pyseq and published under /api/ so the root /objects.inv can resolve stable API URLs.

PySeq is a python module that finds groups of items that follow a naming convention containing a numerical sequence index, e.g.

fileA.001.png, fileA.002.png, fileA.003.png...

and serializes them into a compressed sequence string representing the entire sequence, e.g.

fileA.1-3.png

It should work regardless of where the numerical sequence index is embedded in the name.

Docs and latest version available for download at

http://github.com/rsgalloway/pyseq

exception pyseq.FormatError¶

Bases: Exception

Special exception for Sequence format errors.

class pyseq.Item(item: str | PathLike)¶

Bases: str

Represents a file in a sequence.

property digits¶

Returns the numerical components of the Item as a list of strings.

Returns:: The numerical components.

property dirname¶

Gets the directory name of the Item, if it is a filesystem item.

Returns:: The directory name.

property exists¶

Checks if this Item exists on disk.

Returns:: True if the Item exists, False otherwise.

is_sibling(item: str)¶

Determines if this Item and another Item are part of the same sequence.

Parameters:: item – Another Item instance.
Returns:: True if this Item and the other Item are sequential siblings, False otherwise.

property mtime¶

Returns the modification time of the Item.

Returns:: The modification time.

property name¶

Gets the base name of the Item.

Returns:: The base name.

property number_matches¶

Returns the numerical components of the Item as a list of regex match objects.

Returns:: The numerical components.

property parts¶

Returns the non-numerical components of the Item.

Returns:: The non-numerical components.

property path¶

Gets the absolute path of the Item, if it is a filesystem item.

Returns:: The absolute path.

property size¶

Returns the size of the Item, reported by os.stat.

Returns:: The size of the Item.

property stat¶

Returns the os.stat object for this file.

Returns:: The os.stat object.

class pyseq.Sequence(items: List[str])¶

Bases: list

Extends list class with methods that handle item sequentialness.

For example:

>>> s = Sequence(['file.0001.jpg', 'file.0002.jpg', 'file.0003.jpg'])
>>> print(s)
file.1-3.jpg
>>> s.append('file.0006.jpg')
>>> print(s.format('%4l %h%p%t %R'))
   4 file.%04d.jpg 1-3 6
>>> s.includes('file.0009.jpg')
True
>>> s.includes('file.0009.pic')
False
>>> s.contains('file.0006.jpg')
False
>>> print(s.format('%h%p%t %r (%R)'))
file.%04d.jpg 1-6 (1-3 6)

append(item: Item, check_membership: bool = True)¶

Adds another member to the sequence.

Parameters:

item – pyseq.Item object.
check_membership – Check if item is a member. Can be useful if membership is checked prior to appending.

SequenceError raised if item is not a sequence member.

contains(item: Item)¶

Checks for sequence membership. Calls Item.is_sibling() and returns True if item is part of the sequence.

For example:

>>> s = Sequence(['fileA.0001.jpg', 'fileA.0002.jpg'])
>>> print(s)
fileA.1-2.jpg
>>> s.contains('fileA.0003.jpg')
False
>>> s.contains('fileB.0003.jpg')
False

Parameters:: item – pyseq.Item class object.
Returns:: True if item is a sequence member.

directory()¶

end()¶

Returns:: Last index number in sequence.

extend(items: List[Item], check_membership: bool = True)¶

Add members to the sequence.

Parameters:

items – List of pyseq.Item objects.
check_membership – Check if item is a member. Can be useful if membership is checked prior to appending.

Exc:

SequenceError Raised if any items are not a sequence member.

format(fmt: str = '%4l %h%p%t %R')¶

Format the stdout string.

The following directives can be embedded in the format string. Format directives support padding, for example: “%04l”.

Directive	Meaning
`%s`	sequence start
`%e`	sequence end
`%l`	sequence length
`%f`	list of found files
`%m`	list of missing files
`%M`	explicit missing files [11-14,19-21]
`%p`	padding, e.g. %06d
`%r`	implied range, start-end
`%R`	explicit broken range, [1-10, 15-20]
`%x`	stepped explicit range, 1-10x2, 20
`%d`	disk usage
`%H`	disk usage (human readable)
`%D`	parent directory
`%h`	string preceding sequence number
`%t`	string after the sequence number

Parameters:: fmt – Format string. Default is ‘%4l %h%p%t %R’.
Returns:: Formatted string.

frames()¶

Returns:: List of files in sequence.

head()¶

Returns:: String before the sequence index number.

property human¶: Returns the size of all items in human-readable format.

includes(item: str | Item)¶

Checks if the item can be contained in this sequence, i.e. if it is a sibling of any of the items in the list.

For example:

>>> s = Sequence(['fileA.0001.jpg', 'fileA.0002.jpg'])
>>> print(s)
fileA.1-2.jpg
>>> s.includes('fileA.0003.jpg')
True
>>> s.includes('fileB.0003.jpg')
False

Parameters:: item – pyseq.Item class object.
Returns:: True if item is a sequence member.

insert(index: int, item: Item, check_membership: bool = True)¶

Add another member to the sequence at the given index.

Parameters:

index – The index at which to insert the item.
item – pyseq.Item object.
check_membership – Check if item is a member. Can be useful if membership is checked prior to appending.

Raises:

SequenceError Raised if item is not a sequence member.

length()¶

Returns:: The length of the sequence.

missing()¶

Returns:: List of missing files.

property mtime¶: Returns the latest mtime of all items.

path()¶

Returns:: Absolute path to sequence.

reIndex(offset: int, padding: int = None)¶

Renames and reindexes the items in the sequence, e.g.

>>> seq.reIndex(offset=100)

will add a 100 frame offset to each Item in seq, and rename the files on disk.

Parameters:

offset – The frame offset to apply to each item.
padding – Change the padding.

property size¶: Returns the size all items in bytes.

start()¶

Returns:: First index number in sequence.

tail()¶

Returns:: String after the sequence index number.

exception pyseq.SequenceError¶

Bases: Exception

Special exception for Sequence errors.

pyseq.diff(f1: str | Item, f2: str | Item)¶

Examines diffs between f1 and f2 and deduces numerical sequence number.

For example

>>> diff('file01_0040.rgb', 'file01_0041.rgb')
[{'frames': ('0040', '0041'), 'start': 7, 'end': 11}]

>>> diff('file3.03.rgb', 'file4.03.rgb')
[{'frames': ('3', '4'), 'start': 4, 'end': 5}]

Parameters:

f1 – pyseq.Item object.
f2 – pyseq.Item object to diff.

Returns:

A dictionary with keys ‘frames’, ‘start’, and ‘end’.

pyseq.get_sequences(source: str, frame_pattern: str = '\\d+')¶

Returns a list of Sequence objects given a directory or list that contain sequential members.

Get sequences in a directory:

>>> seqs = get_sequences('tests/files/')
>>> for s in seqs: print(s)
...
012_vb_110_v001.1-10.png
012_vb_110_v002.1-10.png
a.1-14.tga
alpha.txt
bnc01_TinkSO_tx_0_ty_0.101-105.tif
bnc01_TinkSO_tx_0_ty_1.101-105.tif
bnc01_TinkSO_tx_1_ty_0.101-105.tif
bnc01_TinkSO_tx_1_ty_1.101-105.tif
file.1-2.tif
file.info.03.rgb
file01_40-43.rgb
file02_44-47.rgb
file1-4.03.rgb
file_02.tif
z1_001_v1.1-4.png
z1_002_v1.1-4.png
z1_002_v2.1-4.png

Get sequences from a list of file names:

>>> seqs = get_sequences(['fileA.1.rgb', 'fileA.2.rgb', 'fileB.1.rgb'])
>>> for s in seqs: print(s)
...
fileA.1-2.rgb
fileB.1.rgb

Parameters:

source – Can be directory path, list of strings, or sortable list of objects.
frame_pattern – Regular expression pattern for frame matching.

Returns:

List of pyseq.Sequence class objects.

pyseq.iget_sequences(source: str, frame_pattern: str = '\\d+')¶

Generator version of get_sequences. Creates Sequences from a various source files. A notable difference is the sort order of iget_sequences versus get_sequences. iget_sequences uses an adaption of natural sorting that starts with the file extension. Because of this, Sequences are returned ordered by their file extension.

Get sequences in a directory:

>>> seqs = iget_sequences('./tests/files/')
>>> for s in seqs: print(s)
...
file01.1-4.j2k
fileA.1-3.jpg
012_vb_110_v001.1-10.png
012_vb_110_v002.1-10.png
fileA.1-3.png
z1_001_v1.1-4.png
z1_002_v1.1-4.png
z1_002_v2.1-4.png
file1.03.rgb
file01_40-43.rgb
file2.03.rgb
file02_44-47.rgb
file3-4.03.rgb
file.info.03.rgb
a.1-14.tga
bnc01_TinkSO_tx_0_ty_0.101-105.tif
bnc01_TinkSO_tx_0_ty_1.101-105.tif
bnc01_TinkSO_tx_1_ty_0.101-105.tif
bnc01_TinkSO_tx_1_ty_1.101-105.tif
file.1-2.tif
file_02.tif
alpha.txt

Get sequences from a list of file names:

>>> seqs = iget_sequences(['fileA.1.rgb', 'fileA.2.rgb', 'fileB.1.rgb'])
>>> for s in seqs: print(s)
...
fileA.1-2.rgb
fileB.1.rgb

Parameters:

source – Can be directory path, list of strings, or sortable list of objects.
frame_pattern – Regular expression pattern for frame matching.

Yield:

pyseq.Sequence class objects.

pyseq.padsize(item, frame)¶

Determine the pad size for a given Item.

The return value may depend on whether strict padding is enabled.

For example: the file item.001.exr will have a pad size of 3, and the file test.001001.exr will have a pad size of 6.

Signed frames use the digit width only; the leading - does not contribute to the padding width.

Parameters:

item – Item object.
frame – The frame number token as a string.

Returns:

The size of the frame pad as an int.

pyseq.uncompress(seq_string: str, fmt: str = '%4l %h%p%t %R')¶

Deserialize a compressed sequence string into a Sequence.

For example:

>>> seq = pyseq.uncompress('012_vb_110_v001.%04d.png 1-10', fmt='%h%p%t %r')
>>> print(seq)
012_vb_110_v001.1-10.png
>>> len(seq)
10
>>> seq = pyseq.uncompress('a.%03d.tga [1-3, 10, 12-14]', fmt='%h%p%t %R')
>>> print(seq)
a.1-14.tga
>>> len(seq)
7
>>> seq = pyseq.uncompress('a.%03d.tga 1-14 ([1-3, 10, 12-14])', fmt='%h%p%t %r (%R)')
>>> print(seq)
a.1-14.tga
>>> len(seq)
7
>>> seq = pyseq.uncompress('a.1-100.exr', fmt='%h%r%t')
>>> print(seq)
a.1-100.exr
>>> len(seq)
100

>>> seq = pyseq.uncompress('render.%04d.exr 1001-1010x3', fmt='%h%p%t %x')
>>> print(seq.frames())
[1001, 1004, 1007, 1010]

Parameters:

seq_string – Compressed sequence string.
fmt – Format of sequence string.

Returns:

Sequence instance, or None when the string does not match fmt.

pyseq.walk(source: str, level: int = -1, topdown: bool = True, onerror: Callable[[str, OSError], None] = None, followlinks: bool = False, hidden: bool = False)¶

Generator that traverses a directory structure starting at source looking for sequences.

Parameters:

source – Valid folder path to traverse.
level – int, if < 0 traverse entire structure otherwise traverse to given depth.
topdown – Walk from the top down.
onerror – Callable to handle os.listdir errors.
followlinks – Whether to follow links.
hidden – Include hidden files and dirs.

Yield:

Tuple of (directory, directories, sequences).

pyseq

Navigation

Related Topics

API Reference¶