fileseq

3.1.1 · active · verified Thu Apr 16

fileseq (version 3.1.1) is a Python library designed for robust parsing and manipulation of file sequences and frame ranges commonly found in VFX and animation workflows. It supports various frame range shorthands, including standard, comma-delimited, chunked, and staggered ranges, as well as negative frames and subframes. The library maintains an active development status with regular patch and minor releases.

Common errors

```
FileSeqException: Cannot parse "//server/share/path.1-10#.exr"
```
cause In versions prior to v3.1.1, `fileseq` could incorrectly strip leading root path separators from UNC paths, causing parsing failures or incorrect path construction.

fix Upgrade `fileseq` to version 3.1.1 or newer to fix UNC path parsing issues.
```
AttributeError: 'FileSequence' object has no attribute 'setExtention'
```
cause You are attempting to use the deprecated and misspelled method `setExtention()` instead of the correct `setExtension()`.

fix Change your code to use `my_sequence.setExtension(ext)`.
```
The ANTLR Tool version 4.x.y used for code generation does not match the current runtime version 4.x.z
```
cause This error typically indicates a mismatch between the ANTLR grammar version used to generate `fileseq`'s parser and the `antlr4-runtime` version available in your environment. While `fileseq` v3.1.0+ vendors its runtime internally, older `fileseq` versions or conflicts with other libraries can expose this problem.

fix For `fileseq` v3.1.0+, ensure no other Python libraries are forcing a conflicting `antlr4-runtime` dependency. For older `fileseq` versions, try to align the `antlr4-runtime` version in your environment with the one expected by `fileseq`, or preferably, upgrade `fileseq` to version 3.1.0 or newer to benefit from the vendored runtime.
```
fileseq.findSequencesOnDisk("path/to/single_file.exr") returns an empty list or an unexpected FileSequence object for a single file.
```
cause Older versions of `fileseq` might have had issues with aggressively identifying single files as sequences or inconsistencies in the `findSequencesInList` logic.

fix Ensure `fileseq` is at `v1.15.3` or newer for improvements in `yield_sequences_in_list` logic. When using `findSequencesOnDisk`, if dealing with subframes, ensure you explicitly set `allow_subframes=True`.

Warnings

breaking Version 3.0.0 introduced significant architectural changes, including a complete rewrite of the internal parsing engine using ANTLR4 instead of regular expressions. While much of the API remains compatible, subtle behavioral differences or changes in how highly complex or edge-case sequence patterns are parsed might occur compared to v2.x versions.
Fix: Thoroughly test existing parsing logic after upgrading to v3.0.0+.
gotcha As of v3.1.0, the `antlr4-runtime` dependency was vendored internally to prevent version conflicts with other libraries in the same environment. If you previously manually managed or relied on an external `antlr4-runtime` alongside `fileseq`, this external dependency is no longer required and attempting to force specific versions might lead to unexpected behavior.
Fix: Remove any explicit `antlr4-runtime` dependencies if `fileseq` v3.1.0+ is installed. Allow `fileseq` to manage its internal parser dependency.
gotcha Older versions (prior to v3.1.1) had issues with correctly handling UNC paths (e.g., `//server/share/`) where the leading root path separator could be incorrectly stripped, leading to malformed paths or `FileNotFoundError` when resolving.
Fix: Upgrade to `fileseq` version 3.1.1 or newer to ensure correct parsing and preservation of root path separators in UNC paths.
deprecated The `FileSequence.setExtention()` method (with an 'e') was deprecated in favor of `FileSequence.setExtension()` (with an 's') in older versions. While the misspelled version might still function, it is not officially supported and should be updated.
Fix: Replace `my_sequence.setExtention(ext)` with `my_sequence.setExtension(ext)`.

Install

pip install fileseq Install latest version

Imports

FileSequence
```
from fileseq import FileSequence
```
FrameSet
```
from fileseq import FrameSet
```
FilePathSequence
```
from fileseq import FilePathSequence
```
For pathlib.Path integration (added in v2.2.0)

Quickstart

Demonstrates how to create `FileSequence` and `FrameSet` objects, access their properties, iterate through individual file paths, and utilize `FilePathSequence` for pathlib.Path integration.

from fileseq import FileSequence, FrameSet, FilePathSequence

# Create a FileSequence from a string pattern
seq_str = "/path/to/render/my_shot.1001-1010#.exr"
sequence = FileSequence(seq_str)

print(f"Original sequence: {sequence}")
print(f"Directory: {sequence.dirname()}")
print(f"Basename: {sequence.basename()}")
print(f"Frame range: {sequence.frameRange()}")
print(f"Padding: {sequence.padding()}")

# Iterate over individual file paths
print("Individual files:")
for frame_path in sequence:
    print(f"  {frame_path}")

# Access frames via FrameSet
frames = FrameSet("1-100x5") # Every fifth frame from 1 to 100
print(f"\nFrameSet 1-100x5: {frames}")
print(f"First frame: {frames.start()}")
print(f"Last frame: {frames.end()}")

# Using FilePathSequence for pathlib.Path objects (v2.2.0+)
path_seq = FilePathSequence("/path/to/images/shot_v01.1-50@@.jpg")
print(f"\nFilePathSequence: {path_seq}")
print(f"First path (pathlib.Path): {path_seq.frame(path_seq.start())}")

view raw JSON →