Location transformers

Location transformers allow you to modify the Location string before it's used to access a file in the storage backend. This is useful for scenarios where you need to perform additional processing or formatting on the location, such as adding prefixes, encoding characters, or generating unique identifiers.

What are location transformers?

A location transformer is a callable (usually a function) that takes the original Location string, optional Upload, and any extra data as input, and returns a modified Location string. They provide a flexible way to customize how locations are handled by file-keeper.

Location transformers are set per-storage via location_transformers option. To apply them call prepare_location() method.

Example

storage = make_storage("test", {
    "type": "file_keeper:fs",
    "location_transformers": ["safe_relative_path"],
    "path": "/tmp",
})

unsafe_location = "../etc/passwd"

safe_location = storage.prepare_location(unsafe_location)

storage.upload(safe_location, ...)

Steps to create a custom location transformer

Define your transformer

Create a function that accepts the Location, optional Upload, and extras as input and returns the transformed Location.

def my_location_transformer(location, upload_or_none, extras):
    # Perform custom transformation here
    return "prefix_" + location

Register the transformer

Use the register_location_transformers hook to register your transformer. This makes it available for use when creating or accessing files.

import file_keeper as fk

@fk.hookimpl
def register_location_transformers(registry):
    registry.register("my_transformer", my_location_transformer)

Using Your Custom Transformer

To use your custom transformer, specify its name when creating a Storage object in the settings.

storage = make_storage("my_storage", {
    "adapter": "s3",
    "location_transformers": ["my_transformer"],
})

And apply Storage.prepare_location to original location:

transformed = storage.prepare_location("hello.txt")

assert transformed == "prefix_hello.txt"