File Naming

The Libera Utils Filename classes allow reliable file naming, checking, and path management to support conformity with the Libera filenaming conventions. Each type of filename contains regex that validates every definition or update of the internally tracked filename string. These classes transparently support both S3 paths and local filepaths, including dynamic switching between the two, to simplify the transition between local development environments and AWS.

Full specifics including all available file naming classes are available in the filenaming API documentation here

Hashing and Equality

All Filename classes are hashable and compare equal when their paths are equal, so they can be used as dictionary keys and set members. Two filenames with the same basename in different directories or buckets are distinct. A filename’s equality check only handles other filenames; for anything else it returns NotImplemented and Python falls back to the other operand, so comparing a filename with a string, None or a path is False. Reassigning path changes the object’s hash, so do not modify a filename that is already a set member or a dictionary key.

Working With Paths

Below is an example test using a LiberaDataProductFilename instance to manage a filename string, including switching between S3 and local paths to show the flexibility of the classes.

from pathlib import Path
from cloudpathlib import S3Path
from libera_utils.io import filenaming

p = filenaming.LiberaDataProductFilename(
    'LIBERA_L2_CF-CAM_V1-2-3_20270102T112233_20270102T122233_R27002112233.nc')
# Add an S3 prefix
p.path = S3Path('s3://bucket') / p.path
assert isinstance(p.path, S3Path)
# Change prefix to local
p.path = Path('/tmp/path') / p.path.name
assert isinstance(p.path, Path)
# Remove basepath altogether
p.path = p.path.name
assert isinstance(p.path, Path)
# Check that providing a bad value for a basepath doesn't pollute the instance's valid path
try:
    p.path = '/bad/prefix' + p.path.name  # The missing / will make this fail regex validation
    raise Exception('The previous line should have raised a ValueError')
except ValueError as e:
    assert "failed validation against regex pattern" in str(e)
assert p.path.name == 'LIBERA_L2_CF-CAM_V1-2-3_20270102T112233_20270102T122233_R27002112233.nc'