framefile

Python library for parsing and matching file name patterns like IMG_####.JPG or IMG_%04d.JPG.

Such files are often created by cameras and video production software. As a rule, this is a set of images with consecutive numbers, like IMG_0001.JPG, IMG_0002.JPG, IMG_0003.JPG and so on.

To handle files such as video sequences, Blender and AE use patterns like IMG_####.JPG. ffmpeg uses patterns like IMG_%04d.JPG.

This package can create and parse patterns in both formats.

Install

pip3 install framefile

pip3 install git+https://github.com/rtmigo/framefile_py@staging#egg=framefile

Use

Guess pattern from file name

from framefile import filename_to_pattern, Format

print(filename_to_pattern(Format.hash, "IMG_4567.JPG"))  # IMG_####.JPG
print(filename_to_pattern(Format.percent, "IMG_4567.JPG"))  # IMG_%04d.JPG

Any names with numbers in them are supported. The path can also be part of the file name.

from framefile import filename_to_pattern, Format

print(filename_to_pattern(Format.hash, "/video/frame-01234.png"))

# /video/frame-#####.png

If there are several number sequences in the file name, only the last of them will be considered a pattern. And only if its length is more than one digit.

from framefile import filename_to_pattern, Format

print(filename_to_pattern(Format.hash, "/video/take505_frame01234.cr2"))

# /video/take505_frame#####.cr2

Guess pattern from directory path

The directory_to_pattern function returns the most common file name pattern found in particular directory.

from pathlib import Path
from framefile import directory_to_pattern, Format

print(directory_to_pattern(Format.hash, Path("/path/to/my_timelapse")))

# /path/to/my_timelapse/img####.jpg

print(directory_to_pattern(Format.percent, Path("/path/to/my_timelapse")))

# /path/to/my_timelapse/img%04d.jpg

Find files by pattern

import glob
import framefile

# print all files matching /path/to/img####.jpg
file_mask = framefile.hash_pattern_to_glob('/path/to/img####.jpg')
print(glob.glob(file_mask))

# print all files matching /path/to/img%04d.jpg
file_mask = framefile.pct_pattern_to_glob('/path/to/img%04d.jpg')
print(glob.glob(file_mask))

Match file names as strings

import re
import framefile

regex = framefile.hash_pattern_to_regex('img####.jpg')
# or framefile.pct_pattern_to_regex('img%04d.jpg')

a = re.match(regex, 'img0023.jpg')
print(a.group(0))  # img0023.jpg
print(a.group(1))  # 0023

b = re.match(regex, 'anything.txt')
print(b)  # None

Extract number from file name

import framefile

x: int = framefile.hash_extract_number("img####.jpg", "img0023.jpg")
print(x)  # 23

y: int = framefile.pct_extract_number("img%04d.jpg", "img0023.jpg")
print(y)  # 23

If the name does not match the pattern, both functions throw the same PatternMismatchError.

import framefile

try:
    z = framefile.hash_extract_number("img####.jpg", "thumbs.db")
except framefile.PatternMismatchError:
    print("Oops!")