# PySequitur
Library for identifying and manipulating sequences of files. It is geared towards visual effects and animation related scenarios, although it can be used with any sequence of files. Emphasis on file system manipulation and flexible handing of anomalous sequences is the main differentiating feature from other similar libraries.
CLI and integration for Nuke coming soon.
No external dependencies, easy to use in VFX pipeline with no privileges.
## Features
- **File Sequence Handling**
- Parse and manage frame-based file sequences
- Support for many naming conventions and patterns
- Handle missing or duplicate frames, inconsistent padding
- **Flexible Component System**
- Parse filenames into components (prefix, delimiter, frame number, suffix, extension)
- Modify individual components while preserving others
- Match sequences against optionally specified components
- **Sequence Operations**
- Rename sequences
- Move sequences around
- Delete sequences
- Copy sequences
- Offset frame numbers
- Adjust or repair frame number padding
## Installation
```bash
# TODO: Add installation instructions once package is published
```
## Quick Start
```python
from pathlib import Path
from pysequitur import FileSequence, Components
# Parse sequences from a directory
sequences = FileSequence.find_sequences_in_path(Path("/path/to/files"))
# Create a virtual sequence from a list of file names
file_list = ["render_001.exr", "render_002.exr", "render_003.exr"]
sequence = FileSequence.find_sequences_in_filename_list(file_list)[0]
# Basic sequence operations
sequence.move_to(Path("/new/directory"))
sequence.rename_to(Components(prefix="new_name"))
sequence.offset_frames(100) # Shift all frame numbers by 100
sequence.delete_files()
new_sequence = sequence.copy_to(Components(prefix="new_name"), Path("/new/directory"))
# Match sequences by components
components = Components(prefix="render", extension="exr")
matches = FileSequence.match_components_in_path(components, Path("/path/to/files"))
# Match sequence by pattern string
sequence = FileSequence.match_sequence_string_in_directory("render_####.exr", Path("/path/to/files"))
```
## Core Classes
### Components
Configuration class for specifying filename components during operations. Any parameter can be None.
```python
components = Components(
prefix="file_name",
delimiter=".",
padding=4,
suffix="_final",
extension="exr",
frame_number=None # Optional frame number for specific frame operations
)
```
Equals: "file_name.####_final.exr"
### FileSequence
Main class.
Manages collections of related Items as a single unit, where Items represent single files.
Key Features:
- Static methods for finding sequences in directories or filename lists
- Match sequences against Components or sequence string patterns
- Sequence manipulation operations (rename, move, copy, delete)
- Frame operations (offset, padding adjustment)
- Sequence analysis (missing frames, duplicates, problems detection)
- Existence status checking (TRUE, FALSE, PARTIAL)
## File Naming Convention
The library parses filenames into the following components:
```
<prefix><delimiter><frame><suffix>.<extension>
```
Example: `render_001_final.exr`
- prefix: "render"
- delimiter: "_"
- frame: "001"
- suffix: "_final"
- extension: "exr"
---
See examples folder for more usage scenarios
Raw data
{
"_id": null,
"home_page": "https://github.com/arcadeperfect/pysequitur",
"name": "pysequitur",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "vfx, file-sequence, image-sequence, file-management",
"author": "arcadeperfect",
"author_email": "alexander.harding@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/73/c3/f27c0db39c33e5755e242b70d479c2885e16aa0e3d66c5c9572afbbda68a/pysequitur-0.1.1.tar.gz",
"platform": null,
"description": "# PySequitur\n\nLibrary for identifying and manipulating sequences of files. It is geared towards visual effects and animation related scenarios, although it can be used with any sequence of files. Emphasis on file system manipulation and flexible handing of anomalous sequences is the main differentiating feature from other similar libraries.\n\nCLI and integration for Nuke coming soon.\n\nNo external dependencies, easy to use in VFX pipeline with no privileges.\n\n## Features\n\n- **File Sequence Handling**\n - Parse and manage frame-based file sequences\n - Support for many naming conventions and patterns\n - Handle missing or duplicate frames, inconsistent padding\n\n- **Flexible Component System**\n - Parse filenames into components (prefix, delimiter, frame number, suffix, extension)\n - Modify individual components while preserving others\n - Match sequences against optionally specified components\n \n- **Sequence Operations**\n - Rename sequences\n - Move sequences around\n - Delete sequences\n - Copy sequences\n - Offset frame numbers\n - Adjust or repair frame number padding\n\n## Installation\n\n```bash\n# TODO: Add installation instructions once package is published\n```\n\n## Quick Start\n\n```python\nfrom pathlib import Path\nfrom pysequitur import FileSequence, Components\n\n# Parse sequences from a directory\nsequences = FileSequence.find_sequences_in_path(Path(\"/path/to/files\"))\n\n# Create a virtual sequence from a list of file names\nfile_list = [\"render_001.exr\", \"render_002.exr\", \"render_003.exr\"]\nsequence = FileSequence.find_sequences_in_filename_list(file_list)[0]\n\n# Basic sequence operations\nsequence.move_to(Path(\"/new/directory\"))\nsequence.rename_to(Components(prefix=\"new_name\"))\nsequence.offset_frames(100) # Shift all frame numbers by 100\nsequence.delete_files()\nnew_sequence = sequence.copy_to(Components(prefix=\"new_name\"), Path(\"/new/directory\"))\n\n# Match sequences by components\ncomponents = Components(prefix=\"render\", extension=\"exr\")\nmatches = FileSequence.match_components_in_path(components, Path(\"/path/to/files\"))\n\n# Match sequence by pattern string\nsequence = FileSequence.match_sequence_string_in_directory(\"render_####.exr\", Path(\"/path/to/files\"))\n```\n\n## Core Classes\n\n### Components\n\nConfiguration class for specifying filename components during operations. Any parameter can be None.\n\n```python\ncomponents = Components(\n prefix=\"file_name\",\n delimiter=\".\",\n padding=4,\n suffix=\"_final\",\n extension=\"exr\",\n frame_number=None # Optional frame number for specific frame operations\n)\n```\nEquals: \"file_name.####_final.exr\"\n\n### FileSequence\nMain class.\nManages collections of related Items as a single unit, where Items represent single files.\n\nKey Features:\n- Static methods for finding sequences in directories or filename lists\n- Match sequences against Components or sequence string patterns\n- Sequence manipulation operations (rename, move, copy, delete)\n- Frame operations (offset, padding adjustment)\n- Sequence analysis (missing frames, duplicates, problems detection)\n- Existence status checking (TRUE, FALSE, PARTIAL)\n\n## File Naming Convention\n\nThe library parses filenames into the following components:\n```\n<prefix><delimiter><frame><suffix>.<extension>\n```\n\nExample: `render_001_final.exr`\n- prefix: \"render\"\n- delimiter: \"_\"\n- frame: \"001\"\n- suffix: \"_final\"\n- extension: \"exr\"\n\n---\n\nSee examples folder for more usage scenarios\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "parsing and manipulation tool for file sequences",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/arcadeperfect/pysequitur",
"Repository": "https://github.com/arcadeperfect/pysequitur"
},
"split_keywords": [
"vfx",
" file-sequence",
" image-sequence",
" file-management"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b3fac51c96ae83bf9ad33ebd4ced53295bbb07bed3869f364fe2da339bce7e0b",
"md5": "589b4c65516946d0349214c81facd681",
"sha256": "eb30e686a29432df1acabf8b0f591af52e48777076339b8d89630c697dd834d8"
},
"downloads": -1,
"filename": "pysequitur-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "589b4c65516946d0349214c81facd681",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 23989,
"upload_time": "2025-01-13T00:10:45",
"upload_time_iso_8601": "2025-01-13T00:10:45.838452Z",
"url": "https://files.pythonhosted.org/packages/b3/fa/c51c96ae83bf9ad33ebd4ced53295bbb07bed3869f364fe2da339bce7e0b/pysequitur-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "73c3f27c0db39c33e5755e242b70d479c2885e16aa0e3d66c5c9572afbbda68a",
"md5": "d89fabc4416ea1d62791b90b1cc55622",
"sha256": "55d2d24967df14540879a168231a4bda5dfebce2e3b05fb93c856b90aeb5a639"
},
"downloads": -1,
"filename": "pysequitur-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "d89fabc4416ea1d62791b90b1cc55622",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 18294,
"upload_time": "2025-01-13T00:10:49",
"upload_time_iso_8601": "2025-01-13T00:10:49.164919Z",
"url": "https://files.pythonhosted.org/packages/73/c3/f27c0db39c33e5755e242b70d479c2885e16aa0e3d66c5c9572afbbda68a/pysequitur-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-13 00:10:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "arcadeperfect",
"github_project": "pysequitur",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pysequitur"
}
JSON
