FileRField

Abstract base class for Resource fields that persist data to files.

FileRField provides a framework for RFields that store their data in files on disk. The field stores a file path reference, and subclasses implement custom logic for reading from and writing to these files.

When a Resource is saved: - The dump_to_file method is called with the field value and file path - The file path is stored in the KV_STORE for later retrieval

When a Resource is loaded: - The file path is retrieved from storage - The load_from_file method is called to read and deserialize the data

This is useful for: - Large data that shouldn't be stored in database/KV_STORE directly - Binary data (images, audio, video, archives) - Data formats that benefit from file-based storage (HDF5, Parquet, etc.) - Custom serialization formats

Note: - Fields are never included in dict views (include_in_dict_view=False) - Storage is always KV_STORE (stores file path reference) - Subclasses must implement both load_from_file and dump_to_file methods

Example: ```python import pickle

class PickleRField(FileRField):
    '''RField that stores data as pickle files'''

    def load_from_file(self, file_path: str) -> Any:
        with open(file_path, 'rb') as f:
            return pickle.load(f)

    def dump_to_file(self, r_field_value: Any, file_path: str) -> None:
        with open(file_path, 'wb') as f:
            pickle.dump(r_field_value, f)

class MyResource(Resource):
    large_data = PickleRField()
```

Attributes

include_in_dict_view: boolstorage: RFieldStorage

Functions

__init__

Initialize a FileRField with automatic file-based persistence.

The field is configured to store file path references in KV_STORE and is excluded from dict views since the actual data is in files.

default_value : Any

Default value for the field when not set. Can be: - Primitive value: Used directly as default - Type or Callable: Called without parameters to generate default - None: Field has no default value Defaults to None

deserialize

Deserialize field value by loading data from the file path.

This method is marked as final and cannot be overridden. It delegates to the load_from_file method which must be implemented by subclasses.

r_field_value : str

File path where the data is stored

Return type : Any

dump_to_file

Serialize and save the field value to a file.

This abstract method must be implemented by subclasses to define how data is serialized and written to the file. It is called automatically when the Resource is saved.

The data MUST be written to the exact file path provided. The directory containing the file is guaranteed to exist.

r_field_value : Any

The field value to serialize and save

file_path : str

Absolute path where the data should be saved

get_default_value

Get the default value for this field.

If the default value is a Type or Callable, it will be called to generate a new default value. Otherwise, the default value is returned directly.

This ensures that mutable defaults (like lists or dicts) are not shared between Resource instances.

Return type : Any

load_from_file

Load and deserialize the field value from a file.

This abstract method must be implemented by subclasses to define how data is read and deserialized from the file. It is called automatically when the Resource is loaded.

The file at file_path is guaranteed to exist when this method is called.

file_path : str

Absolute path to the file containing the serialized data

Return type : Any

serialize

Serialize method not used for FileRField.

The actual serialization is handled by dump_to_file which is called by the resource persistence layer. This method exists for interface compatibility but should be ignored.

r_field_value : Any

The field value (ignored)

Return type : str

Have you developed a brick?