Relative File Paths in Local File system

Core Interfaces

class blob_path.backends.local_relative.LocalRelativeBlobPath(relpath: PurePath)

BlobPath modeling a file which is always relative to a root directory that is injected using implicit variables.

Properties:

• Globally Unique: False

The path is simply composed of relpath, a pathlib.PurePath which is the relative path from the root directory

Usage:

relpath = PurePath("hello") / "world.txt"
p = LocalRelativeBlobPath(relpath)
with p.open("r") as f:
   print(f.read())

The path object is a really simple wrapper around pathlib.PurePath and pathlib.Path. The main use-case of this is to provide an API compatible with other storages. This would enable you to seamlessly use your current FS to do file operations.

The path uses an implicit variable IMPLICIT_BLOB_PATH_LOCAL_RELATIVE_BASE_DIR which injects the root directory to use for these paths. This variable is required to be present if you want to use this path Injecting this variable makes this path a bit more flexible for using between different processes.

• Two docker containers mounting the same volume at different mount points can transparently point to file paths correctly by simply changing their IMPLICIT_BLOB_PATH_LOCAL_RELATIVE_BASE_DIR variables

• Same for two servers mounted on an NFS

Providing relative paths like this makes it easy to access file paths across different processes assuming they can access the file system. There is also a footgun here though, you need to make sure that the environment is correctly configured for every process using this path. In terms of the concepts of BlobPath, this path is not “Globally Unique”

delete() → bool

Delete the file if it exists.

How delete happens is based on the underlying storage and is not important. The file might be accessible through other means if the underlying storage keeps some sort of archive (like S3 versioned buckets), but doing an exists should return False once delete is called, no matter what how the underlying storage works. A read on the file using open will raise DoesNotExist if a file is deleted.

Returns:

True if the file existed and was deleted, else False

classmethod deserialise(data: SerialisedBlobPath) → Self

Deserialise a given serialised representation.

Do not use this method directly in your code, you should use blob_path.deserialise.deserialise

Parameters:

data – A SerialisedBlobPath whose kind should always be equal to self.kind

Returns:

A new BlobPath instance

exists() → bool

Check if the file exists.

Returns:

a boolean based on whether the file exists or not

kind = 'blob-path-local-relative'

kind is a globally unique class variable which uniquely identifies a subtype of BlobPath

Each subtype defines its kind which should never clash with any other implementation. kind is used for serialisation

open(mode: str = 'r') → Generator

Open the underlying file in the given mode.

This function mimics the builtin open function. It fetches the file from the underlying storage and opens it. Returns a file handle to the downloaded file. If the file is opened in write mode, it is uploaded back to the cloud when the handle is closed. Currently this function can only be opened with a context manager. (you can’t manually call close right now) If the file is opened using w mode, then the file does not need to exist in the underlying storage

Parameters:

mode – the mode in which the file should be opened. Currently only a is not supported

Returns:

a file handle where the user can read/write data. Once the context is finished, the file is uploaded to the backend if file was opened in w mode

Raises:

blob_path.interface.DoesNotExist – The file does not exist

property parent: LocalRelativeBlobPath

The logical parent of the path.

Behavior is consistent with pathlib.PurePath.parent. In case of an empty path/root path, the current path is returned as is

Returns:

A new BlobPath which is the parent of the current path

serialise() → SerialisedBlobPath

Serialise the BlobPath to JSON-able dict.

The serialisation of LocalRelativeBlobPath is not Globally Unique Due to the path using implicit variables to determine the root directory, two LocalRelativeBlobPath path objects might point to different files when their serialisation are the same

Serialisation

class blob_path.backends.local_relative.Payload(*, relpath_parts: list[str])