pathseq

A pathlib-first library for working with file sequences.

• Multi-dimension ranges (e.g. animated udims)
• pathlib-first API
• Support for UDIM tokens

Getting Started

The following section demonstrates how to install pathseq and some basic usage. Full documentation is available here: https://pathseq.readthedocs.io/en/latest/

Installation

pathseq can be installed from PyPI:

pip install pathseq

Usage

For more detailed usage, see the documentation: https://pathseq.readthedocs.io/en/latest/

Now, let's get started:

>>> from pathseq import PathSequence
>>> seq = PathSequence("tests/fixtures/simple/images.1-5####.exr")
>>> for path in seq:
...     path
...
PosixPath('tests/fixtures/simple/images.0001.exr')
PosixPath('tests/fixtures/simple/images.0002.exr')
PosixPath('tests/fixtures/simple/images.0003.exr')
PosixPath('tests/fixtures/simple/images.0004.exr')
PosixPath('tests/fixtures/simple/images.0005.exr')

>>> seq = PathSequence("tests/fixtures/simple/images.1-5####.exr")
>>> for path in seq:
...     path.touch(exist_ok=True)
...
>>> seq2 = PathSequence("tests/fixtures/simple/images.####.exr")
>>> seq2.with_existing_paths()
... PathSequence("tests/fixtures/simple/images.1-5####.exr")

>>> seq = PathSequence("tests/fixtures/simple/images.1-5####.exr")
>>> seq.parent
PosixPath('tests/fixtures/simple')
>>> seq.parent / PathSequence("images.1-5####.exr")
... PathSequence("tests/fixtures/simple/images.1-5####.exr")

>>> anim_udims = PathSequence("/path/to/textures.1011-1012<UDIM>_1-3#.tex")
>>> for path in anim_udims:
...     path
...
PosixPath('/path/to/textures.1011_1.tex')
PosixPath('/path/to/textures.1011_2.tex')
PosixPath('/path/to/textures.1011_3.tex')
PosixPath('/path/to/textures.1012_1.tex')
PosixPath('/path/to/textures.1012_2.tex')
PosixPath('/path/to/textures.1012_3.tex')

A wide range of sequence string formats are supported:

>>> from pathseq import LoosePathSequence
>>> seq = LoosePathSequence("/path/to/images.1-5####.exr")

>>> seq = LoosePathSequence("/path/to/1-5####_images.exr")
>>> seq[0]
PosixPath('/path/to/0001_images.exr')
>>> seq.suffixes
('.exr',)

>>> LoosePathSequence("/path/to/1-5####_archives.tar.gz").suffixes
('.tar', '.gz')

>>> seq = LoosePathSequence("/path/to/images.exr.1-5####")
>>> seq[0]
PosixPath('/path/to/images.exr.0001')
>>> seq.suffixes
('.exr',)

>>> LoosePathSequence("/path/to/images.1001-1005<UDIM>.exr")[0]
PosixPath('/path/to/images.1001.exr')

>>> LoosePathSequence("/path/to/images.1001-1005<UVTILE>.exr")[0]
PosixPath('/path/to/images.u1_v1.exr')

Contributing

Running the tests

Tests are executed through tox.

tox

Code Style

Code is formatted using ruff.

You can check your formatting using ruff's check mode:

tox -e format

You can also get ruff to format your changes for you:

tox -e autoformat

Release Notes

Release notes are managed through towncrier. When making a pull request you will need to create a news fragment to document your change:

tox -e release_notes -- create --help

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the MIT License. See the LICENSE.rst file for details.