pyseq - Python sequence string module

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.

Source Code

PySeq’s git repo is available on GitHub, which can be browsed at:

and cloned using:

$ git clone git://github.com/rsgalloway/pyseq.git pyseq

Installation

Installing PySeq is easily done using setuptools. Assuming it is installed, just run the following from the command-line:

$ pip install pyseq

Alternatively, you can install from the distribution using the setup.py script:

$ python setup.py install

Overview

PySeq comes with a command-line script called lss.

$ lss [path] [-f format] [-d]

Using the “z1” file sequence example in the “tests” directory:

$ ls tests/files/z1*
tests/files/z1_001_v1.1.png tests/files/z1_002_v1.3.png
tests/files/z1_001_v1.2.png tests/files/z1_002_v1.4.png
tests/files/z1_001_v1.3.png tests/files/z1_002_v2.1.png
tests/files/z1_001_v1.4.png tests/files/z1_002_v2.2.png
tests/files/z1_002_v1.1.png tests/files/z1_002_v2.3.png
tests/files/z1_002_v1.2.png tests/files/z1_002_v2.4.png

$ lss tests/files/z1*
   4 z1_001_v1.%d.png 1-4
   4 z1_002_v1.%d.png 1-4
   4 z1_002_v2.%d.png 1-4

$ lss tests/files/z1* -f "%h%r%t"
z1_001_v1.1-4.png
z1_002_v1.1-4.png
z1_002_v2.1-4.png

API Examples

Sequence compression

Example using getSequences to compress filesystem sequences starting with “bnc”. The getSequences function will return a list of all sequences found using the given input, which can be either a path or a list.

>>> import pyseq
>>> seqs = pyseq.get_sequences('./tests/files/bnc*')
>>> for s in seqs:
...     print(s.format('%h%p%t %r'))
...
bnc01_TinkSO_tx_0_ty_0.%04d.tif 101-105
bnc01_TinkSO_tx_0_ty_1.%04d.tif 101-105
bnc01_TinkSO_tx_1_ty_0.%04d.tif 101-105
bnc01_TinkSO_tx_1_ty_1.%04d.tif 101-105

Example using the Sequence class with a list as input. The Sequence class constructor will return a single Sequence class instance of sequential items, skipping any items in the list that are not part of the sequence.

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

Iterate over the Sequence members:

>>> for i in s:
...     print i.name,  # file name
...     print i.frame, # unpadded frame number
...     print i.exists # True if file exists on disk
...
file.0001.jpg 1 False
file.0002.jpg 2 False
file.0003.jpg 3 False

Sequence expansion

>>> s = pyseq.uncompress('012_vb_110_v002.1-150.dpx', format="%h%r%t")
>>> len(s)
150
>>> seq = pyseq.uncompress('./tests/012_vb_110_v001.%04d.png 1-10', format='%h%p%t %r')
>>> print(seq.format('%04l %h%p%t %R'))
  10 012_vb_110_v001.%04d.png 1-10

API Reference

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

exception pyseq.SequenceError

Special exception for Sequence errors

exception pyseq.FormatError

Special exception for Sequence format errors

class pyseq.Item(item)

Sequence member file class

Parameters:item – Path to file.
digits

Numerical components of item name.

dirname

“Item directory name, if a filesystem item.”

exists

Returns True if this item exists on disk

isSibling(**kwargs)

Deprecated: use is_sibling instead

is_sibling(item)

Determines if this and item are part of the same sequence.

Parameters:item – An Item instance.
Returns:True if this and item are sequential siblings.
mtime

Returns the modification time of the Item

name

Item base name attribute

parts

Non-numerical components of item name

path

Item absolute path, if a filesystem item.

size

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

stat

Returns the os.stat object for this file.

class pyseq.Sequence(items)

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)

Adds another member to the sequence.

Parameters:item – pyseq.Item object.

SequenceError raised if item is not a sequence member.

contains(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.
end()
Returns:Last index number in sequence
extend(items)

Add members to the sequence. :param items: list of pyseq.Item objects. :exc: SequenceError raised if any items are not a sequence

member.
format(fmt='%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 missingfiles [11-14,19-21]
%p padding, e.g. %06d
%r implied range, start-end
%R explicit broken range, [1-10, 15-20]
%d disk usage
%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.
includes(item)

Checks if the item can be contained in this sequence that is 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
insert(index, item)

Add another member to the sequence at the given index. :param item: pyseq.Item object. :exc: SequenceError raised if item is not a sequence member.

length()
Returns:The length of the sequence.
missing()
Returns:List of missing files.
mtime

Returns the latest mtime of all items

path()
Returns:Absolute path to sequence.
reIndex(offset, padding=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
size

Returns the size all items (divide by 1024*1024 for MBs)

start()
Returns:First index number in sequence
tail()
Returns:String after the sequence index number.
pyseq.diff(f1, f2)

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, for comparison.
Returns:

Dictionary with keys: frames, start, end.

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

Basic uncompression or deserialization of a compressed sequence string.

For example:

>>> seq = uncompress('./tests/files/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
>>> seq2 = uncompress('./tests/files/a.%03d.tga [1-3, 10, 12-14]', fmt='%h%p%t %R')
>>> print(seq2)
a.1-14.tga
>>> len(seq2)
7
>>> seq3 = uncompress('a.%03d.tga 1-14 ([1-3, 10, 12-14])', fmt='%h%p%t %r (%R)')
>>> print(seq3)
a.1-14.tga
>>> len(seq3)
7

See unit tests for more examples.

Parameters:
  • seq_string – Compressed sequence string.
  • fmt – Format of sequence string.
Returns:

Sequence instance.

pyseq.getSequences(*args, **kwargs)

Deprecated: use get_sequences instead

pyseq.get_sequences(source)

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

Get sequences from a list of objects, preserving object attrs:

>>> seqs = get_sequences(repo.files())
>>> seqs[0].date
datetime.datetime(2011, 3, 21, 17, 31, 24)
Parameters:source – Can be directory path, list of strings, or sortable list of objects.
Returns:List of pyseq.Sequence class objects.
pyseq.walk(source, level=-1, topdown=True, onerror=None, followlinks=False, hidden=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

Indices and tables