Skip to main content

A nifty way to parse your file sequences.

Project description

PyPi Package Build Status Coverage Status Code Health License


The seqparse module may be used to …

  • Scan specified paths for file sequences and “singletons,”
  • Construct frame and file sequence from supplied values, and
  • Query disk for overall footprint of tracked files.

The module also comes supplied with a simple tool named seqls that allows the user to scan multiple locations for file sequences and singletons from the command line.

If you’re curious about the regular expressions used to determine what is and isn’t a valid file sequence, take a look at the seqparse.regex module.

Frame Sequences

Frame sequences are broken down into comma-separated chunks of the format first frame - last frame x step where the following rules apply:

  • Frame numbers can be zero-padded,
  • Frame step (increment) is always a positive integer,
  • The number of digits in a frame may exceed the padding of a sequence, eg 001,010,100,1000,
  • Frame chunks with a specified step will always consist of three or more frames.

Examples of proper frame sequences:

  • Non-padded sequence, frames == (1, 3, 5, 7): 1-7x2
  • Four-padded sequence, frames == (1, 3, 5, 7): 0001-0007x2
  • Three-padded sequence, frames == (11, 13): 011,013
  • Two-padded sequence (1, 3, 5, 7, 11, 13, 102): 01-07x2,11,13,102

File Sequences

Members of a file sequence can be one of two formats:

  • base_name.frame_sequence.file_extension
  • frame_sequence.file_extension

Examples of valid file sequences:

  • my_little_pony.1-7x2.exr
  • /maya/is/very/strange/01-07x2,11,13,102.tif
  • C:\this\even\works\in\windows\billy.0001-0095.tga


seqls is the command line interface for the seqparse module.

usage: seqls [-h] [-a] [-H] [-l] [--maxdepth MAX_LEVELS]
             [--mindepth MIN_LEVELS] [-m] [-S]
             [search_path [search_path ...]]

Command line tool for listing file sequences. Upon installation of the
package this script will be accessable via ``seqls`` command on the command
line of your choice.

positional arguments:
  search_path           Paths that you'd like to search for file sequences.

optional arguments:
  -h, --help            show this help message and exit
  -a, --all             Do not ignore entries starting with '.'.
  -H, --human-readable  with -l/--long, print sizes in human readable
                        format (e.g., 1K 234M 2G).
  -l, --long            Use a long listing format.
  --maxdepth MAX_LEVELS
                        Descend at most levels (a non-negative integer)
                        MAX_LEVELS of directories below the
                        starting-points. '--maxdepth 0' means scan the
                        starting-points themselves.
  --mindepth MIN_LEVELS
                        Do not scan at levels less than MIN_LEVELS (a non-
                        negative integer). '--mindepth 1' means scan all
                        levels except the starting-points.
  -m, --missing         Whether to invert output file sequences to only
                        report the missing frames.
  -S, --seqs-only       Whether to filter out all non-sequence files.
  -v, --version         Print the version and exit.

Most of the functionality is self-explanatory, but the -m/--missing option is probably the most useful to users generating large sequences of frames on multiple servers.

Say you’re creating imagery for the latest superhero movie – and your render job crashed some time in the early morning.

You’re expecting to see something like this …


… but not everything rendered.

$ cd /renders/superhero_cape_v0001
$ seqls

You can easily figure out the missing frames, though, with the --missing option:

$ seqls --missing

The module

Using the module is fairly simple:

  1. Instantiate a parser (Seqparse instance).
  2. Add files to the parser either
    • via the add_file method, or
    • by scanning a list of locations on disk via the scan_path method.
  3. Create an iterator for all file sequences (FileSequence instances) and singletons (File instances).
  4. Profit.

Example (taken from the Seqparse docstring):

With the following file structure ...


>>> from seqparse.seqparse import Seqparse
>>> parser = Seqparse()
>>> parser.scan_path("test_dir")
>>> for item in parser.output():
...     print(str(item))
>>> for item in parser.output(seqs_only=True):
...     print(str(item))
>>> for item in parser.output(missing=True):
...     print(str(item))

Useful Classes

FrameSequence instances are pretty useful on their own.

>>> from seqparse import get_sequence
>>> seq = get_sequence([1, 2, 3, 4, 8])
>>> print(repr(seq))
FrameSequence(pad=4, frames=set([1, 2, 3, 4, 8]))
>>> print(seq)
>>> for frame in seq:
...     print(frame)
>>> for frame in seq.invert():
...     print(frame)

As are FileSequence instances (which behave similarly; check class documentation for details).

Final Notes

I’m moderately happy with this code – but there’s always room for improvement (and new/exciting features).

Lemme know if you have any requests/complaints/suggestions!

Project details

Release history Release notifications

This version
History Node


History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
seqparse-0.7.3-py2.py3-none-any.whl (27.8 kB) Copy SHA256 hash SHA256 Wheel py2.py3 Dec 9, 2017

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page