### Install Build Tool and Package

Source: https://github.com/justinfx/fileseq/blob/master/README.md

Installs the necessary build tool and the package with development dependencies.

```bash
pip install hatch              # Install build tool
```

```bash
pip install -e ".[dev]"         # Install package with dev dependencies
```

--------------------------------

### Access Frames in a FrameSet using Convenience Methods

Source: https://github.com/justinfx/fileseq/blob/master/README.md

Provides examples of using `start()` and `end()` methods to retrieve the first and last frames of a FrameSet. These methods offer a more readable alternative to indexing.

```python
>>> fs = fileseq.FrameSet("1-100:8")
>>> fs.start() # First frame.
1
>>> fs.end() # Last frame.
98
```

--------------------------------

### start

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Returns the starting frame number of the sequence's FrameSet. If the sequence does not have a frame pattern, it returns 0.

```APIDOC
## start() -> int | float | Decimal

### Description
Returns the start frame of the sequence’s [`FrameSet`](#fileseq.frameset.FrameSet).
Will return 0 if the sequence has no frame pattern.

### Return type
int | float | decimal.Decimal
```

--------------------------------

### FrameSet Comparison Example

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Demonstrates how to check if one FrameSet is greater than another. The comparison considers both content and order.

```python
>>> FrameSet("1-5") > FrameSet("5-1")
False
```

--------------------------------

### FileSequence with Alternate Padding Styles

Source: https://github.com/justinfx/fileseq/blob/master/README.md

Illustrates how to specify different padding styles for FileSequence objects using `pad_style`. The examples show the output for `PAD_STYLE_HASH1` (1-padded) and `PAD_STYLE_HASH4` (4-padded).

```python
>>> seq = fileseq.FileSequence("/foo/bar.1-10#.exr", pad_style=fileseq.PAD_STYLE_HASH1)
>>> list(seq)
['/foo/bar.1.exr',
 '/foo/bar.2.exr',
 '/foo/bar.3.exr',
 '/foo/bar.4.exr',
 '/foo/bar.5.exr',
 '/foo/bar.6.exr',
 '/foo/bar.7.exr',
 '/foo/bar.8.exr',
 '/foo/bar.9.exr',
 '/foo/bar.10.exr']
>>> seq = fileseq.FileSequence("/foo/bar.1-10#.exr", pad_style=fileseq.PAD_STYLE_HASH4)
>>> list(seq)
['/foo/bar.0001.exr',
 '/foo/bar.0002.exr',
 '/foo/bar.0003.exr',
 '/foo/bar.0004.exr',
 '/foo/bar.0005.exr',
 '/foo/bar.0006.exr',
 '/foo/bar.0007.exr',
 '/foo/bar.0008.exr',
 '/foo/bar.0009.exr',
 '/foo/bar.0010.exr']
```

--------------------------------

### Find All Existing Sequences on Disk

Source: https://github.com/justinfx/fileseq/blob/master/README.md

Shows how to use `fileseq.findSequencesOnDisk` to discover all file sequences present in a given directory. The `FilePathSequence.findSequencesOnDisk` classmethod can be used to get results as `pathlib.Path` objects.

```python
seqs = fileseq.findSequencesOnDisk("/show/shot/renders/bty_foo/v1")
```

```python
seqs = fileseq.FilePathSequence.findSequencesOnDisk("/show/shot/renders/bty_foo/v1")
```

--------------------------------

### Get Start Frame

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Retrieves the starting frame number of the sequence's FrameSet. Returns 0 if no frame pattern is defined.

```python
start() → int | float | Decimal
```

--------------------------------

### Build FrameSet from Range

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Use from_range to create a FrameSet from a start and end frame, with an optional step.

```python
>>> FrameSet.from_range(1, 5)
FrameSet('1-5')
```

```python
>>> FrameSet.from_range(1, 10, 2)
FrameSet('1,3,5,7,9')
```

--------------------------------

### FrameSet.from_range(start, end, step=1)

Source: https://context7.com/justinfx/fileseq/llms.txt

A class method to construct a FrameSet directly from numeric start, end, and an optional step value. This avoids the need to write a range string.

```APIDOC
## FrameSet.from_range(start, end, step=1) — construct from numeric bounds

Class method that builds a `FrameSet` directly from integer start, end, and optional step values without writing a range string.

### Examples
```python
from fileseq import FrameSet

fs = FrameSet.from_range(1, 100)
print(str(fs))                   # '1-100'
print(len(fs))                   # 100

fs_step = FrameSet.from_range(0, 50, 5)
print(str(fs_step))              # '0-50x5'
print(list(fs_step))             # [0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50]

try:
    FrameSet.from_range(1, 10, 0)   # zero step raises ValueError
except ValueError as e:
    print(e)                     # step argument must not be zero
```
```

--------------------------------

### Get List of File Paths as pathlib.Path instances

Source: https://github.com/justinfx/fileseq/blob/master/README.md

Demonstrates the usage of `FilePathSequence`, which is similar to `FileSequence` but returns `pathlib.Path` objects instead of strings for file paths. This is useful for integrating with Python's `pathlib` module.

```python
>>> seq = fileseq.FilePathSequence("/foo/bar.1-10#.exr")
>>> [seq[idx] for idx, fr in enumerate(seq.frameSet())]
[PosixPath('/foo/bar.0001.exr'),
 PosixPath('/foo/bar.0002.exr'),
 PosixPath('/foo/bar.0003.exr'),
 PosixPath('/foo/bar.0004.exr'),
 PosixPath('/foo/bar.0005.exr'),
 PosixPath('/foo/bar.0006.exr'),
 PosixPath('/foo/bar.0007.exr'),
 PosixPath('/foo/bar.0008.exr'),
 PosixPath('/foo/bar.0009.exr'),
 PosixPath('/foo/bar.0010.exr')]
```

--------------------------------

### Get List of File Paths from FileSequence

Source: https://github.com/justinfx/fileseq/blob/master/README.md

Shows how to generate a list of all file paths represented by a FileSequence object. This is achieved by iterating through the sequence and accessing each frame's path.

```python
>>> seq = fileseq.FileSequence("/foo/bar.1-10#.exr")
>>> [seq[idx] for idx, fr in enumerate(seq.frameSet())]
['/foo/bar.0001.exr',
 '/foo/bar.0002.exr',
 '/foo/bar.0003.exr',
 '/foo/bar.0004.exr',
 '/foo/bar.0005.exr',
 '/foo/bar.0006.exr',
 '/foo/bar.0007.exr',
 '/foo/bar.0008.exr',
 '/foo/bar.0009.exr',
 '/foo/bar.0010.exr']
```

--------------------------------

### FrameSet String Representation

Source: https://github.com/justinfx/fileseq/blob/master/docs/usage.md

Shows how to get the string representation of a FrameSet, including its frame range.

```python
str(FrameSet('1-10x2'))          # '1-9x2'
FrameSet('1-5,10-20').frameRange # '1-5,10-20'
```

--------------------------------

### Format File Sequence Path

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Format a file sequence path using a template string. Available keys include basename, range, padding, extension, start, end, length, inverted, and dirname. Raises MaxSizeException if the inverted range exceeds MAX_FRAME_SIZE.

```python
seq = FileSequence('/foo/bar.1-10#.exr')
print(seq.format('{basename}.{start:04d}-{end:04d}{extension}'))
# /foo/bar.0001-0010.exr
```

--------------------------------

### FileSequence Accessing Individual Frames

Source: https://github.com/justinfx/fileseq/blob/master/docs/usage.md

Shows how to get the full path for a specific frame number or iterate through all frame paths in a FileSequence.

```python
seq = FileSequence('/render/beauty.1-10#.exr')

seq.frame(1)    # '/render/beauty.0001.exr'
seq[0]          # first frame path (same as seq.frame(seq.start()))
list(seq)       # all 10 file paths as strings
```

--------------------------------

### format

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Formats the file sequence into a string based on a provided template. Supports keys like basename, range, padding, extension, start, end, length, inverted, and dirname.

```APIDOC
## format(template: str = '{basename}{range}{padding}{extension}') -> str

### Description
Return the file sequence as a formatted string according to the given template. Utilizes the python string format syntax.

### Parameters
* **template** (str) - The template string for formatting. Defaults to '{basename}{range}{padding}{extension}'.

### Return type
str

### Raises
* [fileseq.exceptions.MaxSizeException](#fileseq.exceptions.MaxSizeException) – If frame size exceeds `fileseq.constants.MAX_FRAME_SIZE`.
```

--------------------------------

### Construct FrameSet from Numeric Bounds

Source: https://context7.com/justinfx/fileseq/llms.txt

Uses the `from_range` class method to create a FrameSet directly from integer start, end, and step values. Handles potential `ValueError` for a zero step.

```python
from fileseq import FrameSet

fs = FrameSet.from_range(1, 100)
print(str(fs))                   # '1-100'
print(len(fs))                   # 100

fs_step = FrameSet.from_range(0, 50, 5)
print(str(fs_step))              # '0-50x5'
print(list(fs_step))             # [0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50]

try:
    FrameSet.from_range(1, 10, 0)   # zero step raises ValueError
except ValueError as e:
    print(e)                     # step argument must not be zero
```

--------------------------------

### Yield Sequences from Paths with Template

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Iterates over a list of paths, yielding discrete file sequences. A template FileSequence can be provided to guide frame extraction.

```python
paths = [
    '/dir/file_001.0001.ext',
    '/dir/file_002.0001.ext',
    '/dir/file_003.0001.ext',
]
template = FileSequence('/dir/file_#.0001.ext')
seqs = FileSequence.yield_sequences_in_list(paths, template)
# [<FileSequence: '/dir/file_1-3@@@.0001.ext'>]
```

--------------------------------

### Get Path for a Specific Frame

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Return the formatted path for a given frame number or a placeholder character. Numeric values are padded, while other characters are passed through.

```python
seq = FileSequence('/foo/bar.1-10#.exr')
print(seq.frame(1))
# /foo/bar.0001.exr
print(seq.frame('#'))
# /foo/bar.#.exr
```

--------------------------------

### Format File Sequence String

Source: https://context7.com/justinfx/fileseq/llms.txt

Build a custom string representation of a FileSequence using Python's str.format syntax. Available fields include dirname, basename, range, padding, extension, start, end, length, and inverted.

```python
from fileseq import FileSequence

seq = FileSequence('/show/shot/beauty.1-100#.exr')

# Default template: full sequence pattern
print(seq.format('{dirname}{basename}{range}{padding}{extension}'))
# '/show/shot/beauty.1-100#.exr'

# Pattern without range (for software template fields)
print(seq.format('{dirname}{basename}{padding}{extension}'))
# '/show/shot/beauty.#.exr'

# Just basename + extension
print(seq.format('{basename}{extension}'))
# 'beauty..exr'

# Include inverted (gap) frames
seq2 = FileSequence('/out/render.1-10x2#.exr')
print(seq2.format('{basename} range={range} inverted={inverted}'))
# 'render. range=0001-0009x2 inverted=0002-0008x2'

# Metadata fields
print(seq.format('start={start} end={end} length={length}'))
# 'start=1 end=100 length=100'
```

--------------------------------

### Build and Serve Documentation

Source: https://github.com/justinfx/fileseq/blob/master/README.md

Builds the project documentation and serves it locally for viewing.

```bash
hatch run docs:build
```

```bash
hatch run docs:serve  # View at http://localhost:8000
```

--------------------------------

### Filesystem Discovery: findSequencesOnDisk

Source: https://github.com/justinfx/fileseq/blob/master/docs/usage.md

Demonstrates using findSequencesOnDisk to locate all file sequences within a specified directory.

```python
from fileseq import FileSequence

# All sequences in a directory
seqs = FileSequence.findSequencesOnDisk('/show/shot/renders/v001')
for s in seqs:
    print(s)

# Include hidden files (names starting with '.')
seqs = FileSequence.findSequencesOnDisk('/renders', include_hidden=True)
```

--------------------------------

### FileSequence Formatting

Source: https://github.com/justinfx/fileseq/blob/master/docs/usage.md

Demonstrates using the format() method with template strings to construct custom file paths from FileSequence components.

```python
seq = FileSequence('/show/shot/beauty.1-100#.exr')
seq.format('{dirname}{basename}{range}{padding}{extension}')
# '/show/shot/beauty.1-100#.exr'

seq.format('{basename}{extension}')  # 'beauty.exr'
```

--------------------------------

### FileSequence Basic Construction

Source: https://github.com/justinfx/fileseq/blob/master/docs/usage.md

Demonstrates the basic construction of a FileSequence object and accessing its properties like basename, extension, padding, and frame range.

```python
from fileseq import FileSequence

seq = FileSequence('/render/beauty.1-100#.exr')
print(seq.basename())    # 'beauty'
print(seq.extension())   # '.exr'
print(seq.padding())     # '#'
print(seq.frameRange())  # '1-100'
```

--------------------------------

### FileSequence Basename

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Get the basename of the file sequence.

```APIDOC
## FileSequence Basename

### Description
Returns the basename of the sequence.

### Method
`basename()`

### Returns
- **str** - The sequence basename.
```

--------------------------------

### FileSequence String Representation

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Get the string representation of the FileSequence object.

```APIDOC
## FileSequence String Representation

### Description
Provides a string representation of this FileSequence.

### NOTE
A FileSequence that does not define a frame range will omit the padding character component when string formatted, even if the padding character is set. For more control over the exact string format, use the `FileSequence.format()` method.

### Method
`__str__()`

### Return Type
- **str** - The string representation of the FileSequence.
```

--------------------------------

### Construct FrameSet from Range Strings

Source: https://context7.com/justinfx/fileseq/llms.txt

Demonstrates various shorthand notations for constructing FrameSet objects, including standard ranges, steps, fills, staggers, negative frames, comma-delimited ranges, and subframes. Also shows construction from iterables, single values, and copying.

```python
import fileseq
from fileseq import FrameSet

# All supported range shorthands
FrameSet('1-10')          # → 1,2,3,...,10
FrameSet('1-10x2')        # step: 1,3,5,7,9
FrameSet('1-10y2')        # fill (inverse step): 2,4,6,8,10
FrameSet('1-10:3')        # stagger: 1-10x3, 1-10x2, 1-10 (deduplicated)
FrameSet('-5-5')          # negative frames: -5,-4,...,5
FrameSet('1-5,10-20')     # comma-delimited: 1..5 plus 10..20
FrameSet('1-3x0.5')       # subframes: 1.0, 1.5, 2.0, 2.5, 3.0

# Construct from an iterable or a single value
FrameSet([1, 2, 3, 4, 5])
FrameSet(42)              # single frame
FrameSet(FrameSet('1-5')) # copy constructor

# Inspection
fs = FrameSet('1-100x5')
print(len(fs))            # 20
print(fs.start())         # 1
print(fs.end())           # 96
print(fs.frange)          # '1-100x5'
print(5 in fs)            # True
print(2 in fs)            # False

# Iteration and indexing
print(list(fs)[:5])       # [1, 6, 11, 16, 21]
print(fs[0])              # 1
print(fs[-1])             # 96

# Null (empty) FrameSet
null_fs = FrameSet('')
print(null_fs.is_null)    # True
```

--------------------------------

### FileSequence Length

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Get the total number of files represented by the FileSequence object.

```APIDOC
## FileSequence Length

### Description
Returns the length (number of files) represented by this FileSequence.

### Method
`__len__()`

### Return Type
- **int** - The number of files in the sequence.
```

--------------------------------

### Get Zfill Depth

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Returns the number of zeroes used for padding frame numbers.

```python
zfill() → int
```

--------------------------------

### FileSequence Pad Style Configuration

Source: https://github.com/justinfx/fileseq/blob/master/docs/usage.md

Shows how to explicitly set the padding style for a FileSequence, differentiating between the default HASH4 and HASH1 (Houdini) conventions.

```python
from fileseq import FileSequence, PAD_STYLE_DEFAULT, PAD_STYLE_HASH1

# Default: '#' maps to 4-digit zero-padded
seq = FileSequence('/out/f.1-10#.exr', pad_style=PAD_STYLE_DEFAULT)

# Hash1: '#' maps to 1 digit, '####' to 4 digits (Houdini convention)
seq = FileSequence('/out/f.1-10#.exr', pad_style=PAD_STYLE_HASH1)
```

--------------------------------

### Instantiate FileSequence from String

Source: https://github.com/justinfx/fileseq/blob/master/README.md

Illustrates how to create a FileSequence object from a string representation of a file path with a frame range. The `allow_subframes` parameter can be set to True to handle sequences with fractional frames.

```python
fileseq.FileSequence("/foo/bar.1-10#.exr")
fileseq.FileSequence("/foo/bar.1-10x0.25#.#.exr", allow_subframes=True)
```

--------------------------------

### Get FrameSet Object

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Return the FrameSet object associated with the sequence, or None if not specified.

```python
seq = FileSequence('/foo/bar.1-10#.exr')
print(seq.frameSet())
# <FrameSet: 1-10>
```

--------------------------------

### Get Subframe Padding

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Returns the padding characters currently used for subframes within the sequence.

```python
subframePadding() → str
```

--------------------------------

### Get Path for a Specific Index

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Return the path to the file at the specified index within the sequence.

```python
seq = FileSequence('/foo/bar.1-10#.exr')
print(seq.index(0))
# /foo/bar.0001.exr
```

--------------------------------

### Format FilePath using FileSequence.format Method

Source: https://github.com/justinfx/fileseq/blob/master/README.md

Demonstrates using the `format` method of a FileSequence object to construct a file path string based on a template. This is useful for generating paths with specific padding and structure.

```python
>>> seq = fileseq.FileSequence("/foo/bar.1-10#.exr")
>>> seq.format(template='{dirname}{basename}{padding}{extension}') 
"/foo/bar.#.exr"
>>> seq = fileseq.FileSequence("/foo/bar.1-10#.#.exr", allow_subframes=True)
>>> seq.format(template='{dirname}{basename}{padding}{extension}')
"/foo/bar.#.#.exr"
```

--------------------------------

### FileSequence Non-frame Files

Source: https://github.com/justinfx/fileseq/blob/master/docs/usage.md

Demonstrates creating a FileSequence for files without a frame range, such as configuration files.

```python
seq = FileSequence('/render/config.json')
seq.frameRange()  # ''
seq.frame('')     # '/render/config.json'
```

--------------------------------

### Get File Sequence Padding Characters

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Retrieve the padding characters used in the file sequence.

```python
seq = FileSequence('/foo/bar.0001.exr')
print(seq.padding())
# ####
```

--------------------------------

### Run Tests

Source: https://github.com/justinfx/fileseq/blob/master/README.md

Executes the project tests, with an option to generate a coverage report.

```bash
hatch run test
```

```bash
hatch run test-cov  # with coverage report
```

--------------------------------

### Get Padding Style

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Return the padding style of the sequence. Supported styles include PAD_STYLE_HASH1 and PAD_STYLE_HASH4.

```python
seq = FileSequence('/foo/bar.0001.exr')
print(seq.padStyle())
# <PAD_STYLE: HASH4>
```

--------------------------------

### Get Padding Characters for a Number

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Generate the appropriate padding characters for a given number and padding style.

```python
print(FileSequence.getPaddingChars(1, pad_style='hash4'))
# ####
print(FileSequence.getPaddingChars(1, pad_style='hash1'))
# #
print(FileSequence.getPaddingChars(1, pad_style='default'))
# 0001
```

--------------------------------

### FileSequence Alternative Padding Styles

Source: https://github.com/justinfx/fileseq/blob/master/docs/usage.md

Illustrates FileSequence construction with different padding styles, including 3-digit, printf-style, and Houdini-style.

```python
FileSequence('/render/beauty.1-10@@@.exr')    # 3-digit padding
FileSequence('/render/beauty.1-10%04d.exr')   # printf-style
FileSequence('/render/beauty.1-10$F4.exr')    # Houdini-style
```

--------------------------------

### Get Formatted Frame Range

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Return the string-formatted frame range of the sequence. Returns an empty string if the sequence has no frame pattern.

```python
seq = FileSequence('/foo/bar.1-10#.exr')
print(seq.frameRange())
# 1-10
```

--------------------------------

### Handle fileseq Exceptions (Python)

Source: https://context7.com/justinfx/fileseq/llms.txt

Demonstrates how to catch and handle ParseException, MaxSizeException, and FileSeqException when working with fileseq objects. Adjust MAX_FRAME_SIZE to test MaxSizeException.

```python
from fileseq import FrameSet, FileSequence
from fileseq.exceptions import ParseException, MaxSizeException, FileSeqException
import fileseq.constants as const

# ParseException
try:
    FrameSet('not-a-range')
except ParseException as e:
    print(f"Parse error: {e}")

try:
    FileSequence('invalid/path/with/no.padding')
except ParseException as e:
    print(f"Seq parse error: {e}")

# MaxSizeException — triggered when range is too large
original_max = const.MAX_FRAME_SIZE
const.MAX_FRAME_SIZE = 100  # artificially low for demo
try:
    FrameSet('1-1000')
except MaxSizeException as e:
    print(f"Size error: {e}")   # Frame size 1000 > 100 (MAX_FRAME_SIZE)
finally:
    const.MAX_FRAME_SIZE = original_max

# FileSeqException from findSequenceOnDisk
try:
    FileSequence.findSequenceOnDisk('/nonexistent/path.#.exr')
except FileSeqException as e:
    print(f"Disk error: {e}")
```

--------------------------------

### Format FilePath using String Joining

Source: https://github.com/justinfx/fileseq/blob/master/README.md

Shows an alternative method for constructing file paths by manually joining components obtained from a FileSequence object. This approach offers fine-grained control over the output format.

```python
>>> seq = fileseq.FileSequence("/foo/bar.1-10#.exr")
>>> ''.join([seq.dirname(), seq.basename(), '%0{}d'.format(len(str(seq.end()))), seq.extension()])
"/foo/bar.%02d.exr"
```

--------------------------------

### FrameSet Regular Expression

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

The regular expression used internally by FrameSet to parse frame range strings. It captures the start and end frames of a sequence.

```python
FRANGE_RE *= re.compile('\n    \\A\n    (-?\\d+(?:\\.\\d+)?)         # start frame\n    (?:                       # optional range\n        -                     #   range delimiter\n        (-?\\d+(?:\\.\\d+)?)     #   end , re.VERBOSE)*
```

--------------------------------

### Iterate a FrameSet in Python

Source: https://github.com/justinfx/fileseq/blob/master/README.md

Demonstrates how to iterate through frames within a FileSet object. Ensure the fileseq library is imported.

```python
fs = fileseq.FrameSet("1-5")
for f in fs:
  print(f)
```

--------------------------------

### Get Padding Number from Characters

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Determine the amount of padding represented by a given string of padding characters and style. Raises ValueError for unsupported characters.

```python
print(FileSequence.getPaddingNum('####', pad_style='hash4'))
# 4
print(FileSequence.getPaddingNum('#', pad_style='hash1'))
# 1
print(FileSequence.getPaddingNum('0001', pad_style='default'))
# 4
```

--------------------------------

### File Sequence Grammar Patterns

Source: https://github.com/justinfx/fileseq/blob/master/docs/grammar.md

Illustrates the four main patterns supported by the grammar for defining file sequences.

```plaintext
sequence
: Full sequence with frame range and padding: /path/file.1-100#.exr

patternOnly
: Padding without explicit frame range: /path/file.#.exr

singleFrame
: Single frame file: /path/file.0100.exr

plainFile
: No frame pattern: /path/file.txt
```

--------------------------------

### Using Custom Subclasses

Source: https://github.com/justinfx/fileseq/blob/master/docs/usage.md

Demonstrates how to use custom subclasses of FileSequence with the find methods.

```APIDOC
## Using Custom Subclasses

### Description
Custom subclasses can be used by calling the find methods directly on the subclass or by passing the subclass via the `klass` argument.

### Usage

**Calling directly on the subclass:**
```python
seqs = VRayFileSequence.findSequencesOnDisk('/renders')
seq  = VRayFileSequence.findSequenceOnDisk('/renders/beauty.<frame04>.exr', strictPadding=True, preserve_padding=True)
seqs = VRayFileSequence.findSequencesInList(paths)
```

**Passing the subclass via the `klass` argument:**
```python
seqs = FileSequence.findSequencesOnDisk('/renders', klass=VRayFileSequence)
seq  = FileSequence.findSequenceOnDisk('/renders/beauty.<frame04>.exr', strictPadding=True, preserve_padding=True, klass=VRayFileSequence)
seqs = FileSequence.findSequencesInList(paths, klass=VRayFileSequence)
```
```

--------------------------------

### FrameSet Construction from Iterables

Source: https://github.com/justinfx/fileseq/blob/master/docs/usage.md

Shows how to create a FrameSet instance from existing lists, single frame numbers, or by copying another FrameSet.

```python
FrameSet([1, 2, 3, 4, 5])
FrameSet(42)              # single frame
FrameSet(FrameSet('1-5')) # copy constructor
```

--------------------------------

### Use FrameSet as a dictionary key

Source: https://context7.com/justinfx/fileseq/llms.txt

FrameSet objects are hashable and can be used as dictionary keys. This example shows how to store and retrieve values using FrameSet objects.

```python
from fileseq import FrameSet

cache = {FrameSet('1-100'): 'full_range'}
print(cache[FrameSet('1-100')])     # 'full_range'
```

--------------------------------

### Find Sequence on Disk

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Use to find sequences on disk. Use '@' or '#' for wildcards. '*' is not supported. Strict padding is not enforced by default.

```python
findSequenceOnDisk('/foo/bar.@.exr')
```

```python
findSequenceOnDisk('/foo/bar.@@@@@.exr')
```

```python
findSequenceOnDisk('/foo/bar.*.exr')
```

--------------------------------

### FileSequence Subframe Sequences

Source: https://github.com/justinfx/fileseq/blob/master/docs/usage.md

Illustrates how to enable and use subframe sequences in FileSequence patterns, allowing for fractional frame numbers.

```python
seq = FileSequence('/render/beauty.1-2x0.5#.#.exr', allow_subframes=True)
list(seq)
# ['/render/beauty.0001.0000.exr',
#  '/render/beauty.0001.5000.exr',
#  '/render/beauty.0002.0000.exr']
```

--------------------------------

### FrameSet Iteration and Indexing

Source: https://github.com/justinfx/fileseq/blob/master/docs/usage.md

Demonstrates how to iterate over a FrameSet, access individual frames by index, check length, and test for frame membership.

```python
fs = FrameSet('1-10x2')

list(fs)    # [1, 3, 5, 7, 9]
fs[0]       # 1
fs[-1]      # 9
len(fs)     # 5
5 in fs     # True
```

--------------------------------

### FileSequence Instantiation

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Instantiates a FileSequence object from a string representing a file path and frame range.

```APIDOC
## FileSequence Instantiation

### Description
Instantiate a FileSequence object from a string representing a filepath over a range of frames.

### Method
`fileseq.filesequence.BaseFileSequence(sequence: str, pad_style: ~fileseq.constants._PadStyle = <PAD_STYLE: HASH4>, allow_subframes: bool = False)`

### Parameters
#### Path Parameters
- **sequence** (str) - Required - The file sequence string (e.g., 'dir/path.1-100#.ext').
- **pad_style** (~fileseq.constants._PadStyle) - Optional - The padding style to use. Defaults to HASH4.
- **allow_subframes** (bool) - Optional - Whether to allow subframes. Defaults to False.

### Raises
- **fileseq.exceptions.MaxSizeException** - If the frame size exceeds `fileseq.constants.MAX_FRAME_SIZE`.
```

--------------------------------

### Find Sequence on Disk with Options

Source: https://context7.com/justinfx/fileseq/llms.txt

Use `findSequenceOnDisk` to locate file sequences. Options like `strictPadding` and `preserve_padding` control how padding is handled. `allow_subframes` enables support for sequences with fractional frame numbers.

```python
seq = FileSequence.findSequenceOnDisk(
    '/renders/beauty.%04d.exr',
    strictPadding=True,
    preserve_padding=True
)
print(seq.padding())  # '%04d'
```

```python
seq = FileSequence.findSequenceOnDisk('/renders/beauty.#.#.exr', allow_subframes=True)
```

```python
try:
    seq = fileseq.findSequenceOnDisk('/renders/missing.#.exr')
except FileSeqException as e:
    print(e)  # no sequence found on disk matching /renders/missing.#.exr
```

--------------------------------

### FileSequence Constructor

Source: https://context7.com/justinfx/fileseq/llms.txt

Represents an ordered sequence of file paths, supporting various padding tokens and frame ranges. Allows for basic construction and access to sequence components.

```APIDOC
## FileSequence(sequence, pad_style=PAD_STYLE_DEFAULT, allow_subframes=False)

### Description
Parses a sequence pattern into a FileSequence object. Represents an ordered sequence of file paths including directory, basename, frame range, padding token, and extension. Supports various padding tokens like `#`, `@`, `%04d`, `$F4`, and `<UDIM>`.

### Parameters
- **sequence** (string) - The file sequence pattern string.
- **pad_style** (enum, optional) - The padding style to use. Defaults to PAD_STYLE_DEFAULT.
- **allow_subframes** (bool, optional) - Whether to allow subframe parsing. Defaults to False.

### Usage Examples
```python
import fileseq
from fileseq import FileSequence, PAD_STYLE_DEFAULT, PAD_STYLE_HASH1

# Basic construction
seq = FileSequence('/render/beauty.1-100#.exr')
print(seq.dirname())     # '/render/'
print(seq.basename())    # 'beauty.'
print(seq.extension())   # '.exr'
print(seq.padding())     # '#'
print(seq.frameRange())  # '0001-0100'
print(seq.start())       # 1
print(seq.end())         # 100
print(len(seq))          # 100

# Access individual frames
print(seq.frame(1))      # '/render/beauty.0001.exr'
print(seq.frame(100))    # '/render/beauty.0100.exr'
print(seq[0])            # '/render/beauty.0001.exr'  (first)
print(seq[-1])           # '/render/beauty.0100.exr'  (last)

# All file paths
paths = list(seq)
print(paths[:3])
# ['/render/beauty.0001.exr', '/render/beauty.0002.exr', '/render/beauty.0003.exr']

# Alternate padding tokens
FileSequence('/render/beauty.1-10@@@.exr')   # 3-digit: beauty.001.exr
FileSequence('/render/beauty.1-10%04d.exr')  # printf-style
FileSequence('/render/beauty.1-10$F4.exr')   # Houdini-style

# PAD_STYLE_HASH1: '#' = 1-digit (Houdini pipeline convention)
seq_h1 = FileSequence('/out/f.1-10#.exr', pad_style=PAD_STYLE_HASH1)
print(seq_h1.frame(5))   # '/out/f.5.exr'

# Subframes (must opt in)
seq_sf = FileSequence('/render/beauty.1-2x0.5#.#.exr', allow_subframes=True)
print(list(seq_sf))
# ['/render/beauty.0001.0000.exr',
#  '/render/beauty.0001.5000.exr',
#  '/render/beauty.0002.0000.exr']

# Sequence with no frame range (single file)
single = FileSequence('/render/config.json')
print(single.frameRange())   # ''
print(list(single))          # ['/render/config.json']
```
```

--------------------------------

### Frame Range with Leading Dot

Source: https://github.com/justinfx/fileseq/blob/master/docs/grammar.md

Parses frame ranges that start with a leading dot. Requires a comma, colon, or dash after the first number. Supports optional decimal step values.

```regex
DOT_FRAME_RANGE: '.' '-'? [0-9]+ [,:-] [0-9xy:,-]* ('.' [0-9]+)?;
```

--------------------------------

### Get inverted frame range (missing frames)

Source: https://context7.com/justinfx/fileseq/llms.txt

The invertedFrameRange() method returns the frame range representing frames within the full extent that are not included in the set, effectively showing the gaps.

```python
from fileseq import FrameSet

fs = FrameSet('1-10x2')         # contains: 1,3,5,7,9
print(fs.invertedFrameRange())  # '2-8x2'  (the missing even frames)

fs2 = FrameSet('1-5,10-15')
print(fs2.invertedFrameRange()) # '6-9'    (gap between the two ranges)

# Empty when consecutive
print(FrameSet('1-10').invertedFrameRange())  # ''
```

--------------------------------

### FrameSet Range Syntax

Source: https://github.com/justinfx/fileseq/blob/master/docs/usage.md

Demonstrates various ways to define frame ranges using strings, including steps, fills, staggers, negative frames, and comma-separated ranges.

```python
from fileseq import FrameSet

FrameSet('1-10')          # 1, 2, 3, …,
FrameSet('1-10x2')        # step: 1, 3, 5, 7, 9
FrameSet('1-10y2')        # fill (inverse step): 2, 4, 6, 8, 10
FrameSet('1-10:3')        # stagger: 1-10x3, 1-10x2, 1-10
FrameSet('-5-5')          # negative frames: -5, -4, …,
FrameSet('1-5,10-20')     # comma-separated ranges
```

--------------------------------

### Frame Range without Leading Dot

Source: https://github.com/justinfx/fileseq/blob/master/docs/grammar.md

Parses frame ranges that do not start with a leading dot. Requires a comma, colon, or dash after the first number. Supports optional decimal step values.

```regex
FRAME_RANGE: '-'? [0-9]+ [,:-] [0-9xy:,-]* ('.' [0-9]+)?;
```

--------------------------------

### Return custom path objects with _create_path

Source: https://github.com/justinfx/fileseq/blob/master/docs/usage.md

Override `_create_path` to control the type of object returned for each frame path. This example shows how to return S3-prefixed URLs instead of local file paths.

```python
from pathlib import Path
from fileseq import FileSequence

class S3FileSequence(FileSequence):
    """Return S3-prefixed paths instead of local paths."""

    BUCKET = 's3://my-studio-bucket'

    def _create_path(self, path_str: str) -> str:
        # Strip the leading slash so the URL is well-formed
        return f'{self.BUCKET}/{path_str.lstrip("/")}'

seq = S3FileSequence('/renders/beauty.1-3#.exr')
seq.frame(1)  # 's3://my-studio-bucket/renders/beauty.0001.exr'
list(seq)
# ['s3://my-studio-bucket/renders/beauty.0001.exr',
#  's3://my-studio-bucket/renders/beauty.0002.exr',
#  's3://my-studio-bucket/renders/beauty.0003.exr']
```

--------------------------------

### Find Sequences on Disk (Advanced Patterns)

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Utilize advanced pattern matching for finding file sequences, including stereo pairs and specific padding styles. The 'strictPadding' option ensures that only files with matching padding lengths are included.

```python
FileSequence.findSequencesOnDisk('/path/to/files/image_stereo_{left,right}.#.jpg')
```

```python
FileSequence.findSequencesOnDisk('/path/to/files/imag?_*_{left,right}.@@@.jpg', strictPadding=True)
```

--------------------------------

### fileseq.utils.xfrange

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Returns a generator that yields frame numbers from a start to a stop value, inclusive, with a specified step. It handles positive and negative steps and ensures the stop value is included if it falls within the range.

```APIDOC
## fileseq.utils.xfrange

### Description
Returns a generator that yields the frames from start to stop, inclusive. In other words it adds or subtracts a frame, as necessary, to return the stop value as well, if the stepped range would touch that value.

### Parameters
#### Path Parameters
- **start** (int) - Required
- **stop** (int) - Required
- **step** (int) - Optional - Note that the sign will be ignored
- **maxSize** (int) - Optional

### Return type
generator

### Raises
fileseq.exceptions.MaxSizeException – if size is exceeded
```

--------------------------------

### Custom Padding Syntax with VRayFileSequence

Source: https://context7.com/justinfx/fileseq/llms.txt

Subclass `FileSequence` and override `_preprocess_sequence` and `_postprocess_sequence` to support custom padding tokens like VRay's `<frameNN>`. These hooks are automatically used by sequence discovery methods.

```python
import re
import fileseq

class VRayFileSequence(fileseq.FileSequence):
    """Support VRay <frameNN> padding tokens (e.g. <frame04> → %04d)."""

    _VRAY_PAD_RE   = re.compile(r'<frame(\d+)>')
    _PRINTF_PAD_RE = re.compile(r'%0?(\d+)d')

    def _preprocess_sequence(self, sequence: str) -> str:
        def to_printf(m):
            w = int(m.group(1))
            return f'%0{w}d' if w > 0 else '%d'
        return self._VRAY_PAD_RE.sub(to_printf, sequence)

    def _postprocess_sequence(self, sequence: str) -> str:
        def to_vray(m):
            return f'<frame{int(m.group(1)):02d}>'
        return self._PRINTF_PAD_RE.sub(to_vray, sequence)

# Construction with embedded range
seq = VRayFileSequence('/render/beauty.1-100<frame04>.exr')
print(seq.padding())            # '%04d'
print(seq.frame(42))            # '/render/beauty.0042.exr'
print(str(seq))                 # '/render/beauty.1-100<frame04>.exr'

# Pattern-only (no range)
seq2 = VRayFileSequence('/render/beauty.<frame04>.exr')
print(seq2.format('{dirname}{basename}{padding}{extension}'))
# '/render/beauty.<frame04>.exr'

# Use directly on the subclass — hooks are picked up automatically
# seqs = VRayFileSequence.findSequencesOnDisk('/renders')
# seq  = VRayFileSequence.findSequenceOnDisk('/renders/beauty.<frame04>.exr',
#                                            strictPadding=True, preserve_padding=True)
```

--------------------------------

### Find One Existing Sequence on Disk

Source: https://github.com/justinfx/fileseq/blob/master/README.md

Demonstrates how to find a single file sequence on disk using `fileseq.findSequenceOnDisk`. This method supports using '@' or '#' as wildcard characters and requires `allow_subframes=True` for subframe sequences.

```python
fileseq.findSequenceOnDisk('/foo/bar.@.exr')
```

```python
fileseq.findSequenceOnDisk('/foo/bar.@@@@@.exr')
```

```python
fileseq.findSequenceOnDisk('/foo/bar.#.#.exr', allow_subframes=True)
```

--------------------------------

### Get Inverted Frame Range

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Return the inverse string-formatted frame range of the sequence. Returns an empty string if the sequence has no frame pattern or includes subframes. Raises MaxSizeException if the new inverted range exceeds MAX_FRAME_SIZE.

```python
seq = FileSequence('/foo/bar.1-10#.exr')
print(seq.invertedFrameRange())
# 10-1
```

--------------------------------

### Find Sequences on Disk (Basic)

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Scan a directory for file sequences. Supports glob-like wildcards in the pattern. Padding characters are converted to wildcards ('#' or '@'). Case-sensitive matching is enforced, treating 'file.1.png' and 'file.2.PNG' as distinct.

```python
FileSequence.findSequencesOnDisk('/path/to/files')
```

--------------------------------

### Set New File Extension

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Update the file extension for the sequence. A leading period is automatically added if none is provided.

```python
seq = FileSequence('/foo/bar.0001.exr')
seq.setExtension('png')
print(seq)
# /foo/bar.0001.png
```

--------------------------------

### Find Sequences in List

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Use this method to get a list of discrete file sequences from a provided list of paths. It does not verify file existence on disk. Specify a custom subclass using the 'klass' argument to construct results of that subclass.

```python
VRayFileSequence.findSequencesInList(paths)
```

```python
FileSequence.findSequencesInList(paths, klass=VRayFileSequence)
```

--------------------------------

### Find Sequence with Custom Subclass and Padding

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Demonstrates finding sequences using a custom subclass (VRayFileSequence) with a specific frame format and preserving padding. This allows for integration with custom sequence types.

```python
VRayFileSequence.findSequenceOnDisk("seq/bar<frame04>.exr",
                                    strictPadding=True,
                                    preserve_padding=True)
```

--------------------------------

### Find Sequence on Disk with Basic Pattern

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Searches for sequences matching a basename, extension, and a wildcard for any frame. This is useful for discovering all files that fit a general naming convention.

```python
FileSequence.findSequenceOnDisk("seq/bar@@@@.exr")
```

--------------------------------

### Python: Grammar-Based Parsing API (v3+)

Source: https://github.com/justinfx/fileseq/blob/master/CHANGES.md

In v3 and later, Fileseq uses a grammar-based parsing API. Instantiate FileSequence with the pattern string; the grammar handles parsing internally.

```python
# v3 - Use grammar-based API
seq = FileSequence(pattern)  # Grammar handles parsing
```

--------------------------------

### copy

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Creates a deep copy of the file sequence.

```APIDOC
## copy() -> Any

### Description
Create a deep copy of this sequence

### Return type
[`FileSequence`](#fileseq.filesequence.FileSequence)
```

--------------------------------

### copy() -> [FrameSet](#fileseq.frameset.FrameSet)

Source: https://github.com/justinfx/fileseq/blob/master/docs/api.md

Creates and returns a deep copy of the current FrameSet object.

```APIDOC
## copy() -> [FrameSet](#fileseq.frameset.FrameSet)

### Description
Create a deep copy of this [`FrameSet`](#fileseq.frameset.FrameSet).

### Return type:
  [`FrameSet`](#fileseq.frameset.FrameSet)
```