octoprint.filemanager.storage#

`LocalFileStorage(basefolder, create = False, really_universal = False)` #

Bases: StorageInterface

The LocalFileStorage is a storage implementation which holds all files, folders and metadata on disk.

Metadata is managed inside .metadata.json files in the respective folders, indexed by the sanitized filenames stored within the folder. Metadata access is managed through an LRU cache to minimize access overhead.

This storage type implements path_on_disk.

Initializes a LocalFileStorage instance under the given basefolder, creating the necessary folder if necessary and create is set to True.

Parameters:

basefolder (str) –

the path to the folder under which to create the storage
create (bool) –

True if the folder should be created if it doesn't exist yet, False otherwise
really_universal (bool) –

True if the file names should be forced to be really universal, False otherwise

`sanitize(path)` #

Returns a (path, name) tuple derived from the provided path.

path may be: - a storage path - an absolute file system path - a tuple or list containing all individual path elements - a string representation of the path - with or without a file name

Note

For a path without a trailing slash the last part will be considered a file name and hence be returned at second position. If you only need to convert a folder path, be sure to include a trailing slash for a string path or an empty last element for a list path.

Parameters:

path (str | list | tuple) –

The path to sanitize

Returns:

tuple –

The sanitized path and name

`sanitize_name(name)` #

Sanitizes the given name using sanitize_filename.

Strips any leading ..

Parameters:

name (str) –

The name to sanitize

Returns:

str –

The sanitized name

Raises:

ValueError –

If the name contains / or \

`sanitize_path(path)` #

Sanitizes the given path.

Ensures that the on disk representation of path is located under the configured basefolder. Resolves all relative path elements (e.g. ..) and sanitizes folder names using sanitize_name. The final path is the absolute path, including the leading basefolder path.

Parameters:

path (str) –

The path to sanitize

Returns:

str –

The sanitized path

`StorageInterface` #

Interface of storage adapters for OctoPrint.

`analysis_backlog` `property` #

Get an iterator over all items stored in the storage that need to be analysed by the AnalysisQueue.

The yielded elements are expected as storage specific absolute paths to the respective files. Don't forget to recurse into folders if your storage adapter supports those.

Returns:

iterator –

an iterator yielding all un-analysed files in the storage

`add_file(path, file_object, printer_profile = None, links = None, allow_overwrite = False, display = None)` #

Adds the file file_object as path

Parameters:

path (str) –

the path of the new file, will be sanitized
file_object (object) –

a file object that provides a save method which will be called with the destination path where the object should then store its contents
printer_profile (object) –

the printer profile associated with this file (if any)
links (list) –

any links to add with the file
allow_overwrite (bool) –

if set to True no error will be raised if the file already exists and the existing file and its metadata will just be silently overwritten
display (str) –

display name of the file

Returns:

str –

the sanitized name of the file to be used for future references to it

`add_folder(path, ignore_existing = True, display = None)` #

Adds a folder as path

The path will be sanitized.

Parameters:

path (str) –

the path of the new folder
ignore_existing (bool) –

if set to True, no error will be raised if the folder to be added already exists
display (str) –

display name of the folder

Returns:

str –

the sanitized name of the new folder to be used for future references to the folder

`add_link(path, rel, data)` #

Adds a link of relation rel to file path with the given data.

The following relation types are currently supported:

model: adds a link to a model from which the file was created/sliced, expected additional data is the name and optionally the hash of the file to link to. If the link can be resolved against another file on the current path, not only will it be added to the links of name but a reverse link of type machinecode referring to name and its hash will also be added to the linked model file
machinecode: adds a link to a file containing machine code created from the current file (model), expected additional data is the name and optionally the hash of the file to link to. If the link can be resolved against another file on the current path, not only will it be added to the links of name but a reverse link of type model referring to name and its hash will also be added to the linked model file.
web: adds a location on the web associated with this file (e.g. a website where to download a model), expected additional data is a href attribute holding the website's URL and optionally a retrieved attribute describing when the content was retrieved

Note that adding model links to files identifying as models or machinecode links to files identifying as machine code will be refused.

Parameters:

path (str) –

path of the file for which to add a link
rel (str) –

type of relation of the link to add (currently model, machinecode and web are supported)
data (dict) –

additional data of the link to add

`canonicalize(path)` #

Canonicalizes the given path.

The path may consist of both folder and file name, the underlying implementation must separate those if necessary.

By default, this calls StorageInterface.sanitize, which also takes care of stripping any invalid characters.

Parameters:

path (str) –

the path to canonicalize

Returns:

tuple –

a 2-tuple containing the canonicalized path and file name

`copy_file(source, destination)` #

Copies the file source to destination

Parameters:

source (str) –

path to the source file
destination (str) –

path to destination

Returns:

str –

the new path in the storage to the copy of the file

`copy_folder(source, destination)` #

Copies the folder source to destination

Parameters:

source (str) –

path to the source folder
destination (str) –

path to destination

Returns:

str –

the new path in the storage to the copy of the folder

`file_exists(path)` #

Returns whether the file indicated by path exists or not.

Parameters:

path (str) –

the path to check for existence

Returns:

bool –

True if the file exists, False otherwise

`file_in_path(path, filepath)` #

Returns whether the file indicated by file is inside path or not.

Parameters:

path (str) –

the path to check
filepath (str) –

path to the file

Returns:

bool –

True if the file is inside the path, False otherwise

`folder_exists(path)` #

Returns whether the folder indicated by path exists or not.

Parameters:

path (str) –

the path to check for existence

Returns:

bool –

True if the folder exists, False otherwise

`get_additional_metadata(path, key)` #

Fetches additional metadata at key from the metadata of path.

Parameters:

path (str) –

virtual path to the file for which to fetch additional metadata
key (str) –

key of metadata to fetch

`get_metadata(path)` #

Retrieves the metadata for the file path.

Parameters:

path (str) –

virtual path to the file for which to retrieve the metadata

Returns:

dict –

the metadata associated with the file

`has_analysis(path)` #

Returns whether the file at path has been analysed yet

Parameters:

path (str) –

path to the file to check

`join_path(*path)` #

Join path elements together

Parameters:

path (str) –

the path elements to join

Returns:

str –

joined representation of the path to be usable as fully qualified path for further operations

`last_modified(path = None, recursive = False)` #

Get the last modification date of the specified path or path's subtree.

Parameters:

path (str | None) –

Path for which to determine the subtree's last modification date. If left out or set to None, defaults to storage root.
recursive (bool) –

Whether to determine only the date of the specified path (False, default) or the whole path's subtree (True).

Returns:

float –

The last modification date of the indicated subtree

`list_files(path = None, filter = None, recursive = True, level = 0, force_refresh = False)` #

List all files in storage starting at path. If recursive is set to True (the default), also dives into subfolders.

An optional filter function can be supplied which will be called with a file name and file data and which has to return True if the file is to be included in the result or False if not.

The data structure of the returned result will be a dictionary mapping from file names to entry data. File nodes will contain their metadata here, folder nodes will contain their contained files and folders.

Example

{
    "some_folder": {
        "name": "some_folder",
        "path": "some_folder",
        "type": "folder",
        "children": {
            "some_sub_folder": {
                "name": "some_sub_folder",
                "path": "some_folder/some_sub_folder",
                "type": "folder",
                "typePath": ["folder"],
                "children": { ... }
            },
            "some_file.gcode": {
                "name": "some_file.gcode",
                "path": "some_folder/some_file.gcode",
                "type": "machinecode",
                "typePath": ["machinecode", "gcode"],
                "hash": "<sha1 hash>",
                "links": [ ... ],
                ...
            },
            ...
        }
    "test.gcode": {
        "name": "test.gcode",
        "path": "test.gcode",
        "type": "machinecode",
        "typePath": ["machinecode", "gcode"],
        "hash": "<sha1 hash>",
        "links": [...],
        ...
    },
    "test.stl": {
        "name": "test.stl",
        "path": "test.stl",
        "type": "model",
        "typePath": ["model", "stl"],
        "hash": "<sha1 hash>",
        "links": [...],
        ...
    },
    ...
}

Parameters:

path (str) –

base path from which to recursively list all files, optional, if not supplied listing will start from root of base folder
filter (function) –

a filter that matches the files that are to be returned, may be left out in which case no filtering will take place
recursive (bool) –

will also step into sub folders for building the complete list if set to True, otherwise will only do one step down into sub folders to be able to populate the children.

Returns:

dict –

a nested dictionary mapping entry names to entry data that represents the whole file list

`move_file(source, destination)` #

Moves the file source to destination

Parameters:

source (str) –

path to the source file
destination (str) –

path to destination

Returns:

str –

the new path in the storage to the file

`move_folder(source, destination)` #

Moves the folder source to destination

Parameters:

source (str) –

path to the source folder
destination (str) –

path to destination

Returns:

str –

the new path in the storage to the folder

`path_in_storage(path)` #

Retrieves the equivalent in the storage adapter for path.

Opposite of path_on_disk.

Parameters:

path (str) –

the path on disk for which to retrieve the storage path

Returns:

str –

the path in storage to path

`path_on_disk(path)` #

Retrieves the path on disk for path.

Note

If the storage is not on disk and there exists no path on disk to refer to it, this method should raise an io.UnsupportedOperation

Opposite of path_in_storage.

Parameters:

path (str) –

the virtual path for which to retrieve the path on disk

Returns:

str –

the path on disk to path

`remove_additional_metadata(path, key)` #

Removes additional metadata under key for name on path

Parameters:

path (str) –

virtual path to the file for which to remove additional metadata
key (str) –

key of metadata to remove

`remove_file(path)` #

Removes the file at path

Will also take care of deleting the corresponding entries in the metadata and deleting all links pointing to the file.

Parameters:

path (str) –

path of the file to remove

`remove_folder(path, recursive = True)` #

Removes the folder at path

Parameters:

path (str) –

the path of the folder to remove
recursive (bool) –

if set to True, contained folders and files will also be removed, otherwise an error will be raised if the folder is not empty (apart from any metadata files) when it's to be removed

`remove_link(path, rel, data)` #

Removes the link consisting of rel and data from file path.

Parameters:

path (str) –

path of the file from which to remove the link
rel (str) –

type of relation of the link to remove (currently model, machinecode and web are supported)
data (dict) –

additional data of the link to remove, must match existing link

`sanitize(path)` #

Sanitizes the given path, stripping it of all invalid characters.

The path may consist of both folder and file name, the underlying implementation must separate those if necessary and sanitize individually.

Parameters:

path (str) –

the path to sanitize

Returns:

tuple –

a 2-tuple containing the sanitized path and file name

`sanitize_name(name)` #

Sanitizes the given file name, stripping it of all invalid characters.

Parameters:

name (str) –

the file name to sanitize

Returns:

str –

the sanitized file name

`sanitize_path(path)` #

Sanitizes the given folder-only path, stripping it of all invalid characters.

Parameters:

path (str) –

the path to sanitize

Returns:

str –

the sanitized path

`set_additional_metadata(path, key, data, overwrite = False, merge = False)` #

Adds additional metadata to the metadata of path. Metadata in data will be saved under key.

If overwrite is set and key already exists in path's metadata, the current value will be overwritten.

If merge is set and key already exists and both data and the existing data under key are dictionaries, the two dictionaries will be merged recursively.

Parameters:

path (str) –

virtual path to the file for which to add additional metadata
key (str) –

key of metadata to add
data (dict) –

metadata to add
overwrite (bool) –

if set to True and key already exists, it will be overwritten
merge (bool) –

if set to True and key already exists and both data and the existing data are dictionaries, they will be merged

`split_path(path)` #

Split path into base directory and file name.

Parameters:

path (str) –

the path to split

Returns:

tuple –

a 2-tuple containing the base directory and file name

octoprint.filemanager.storage#

LocalFileStorage(basefolder, create = False, really_universal = False) #

sanitize(path) #

sanitize_name(name) #

sanitize_path(path) #

StorageInterface #

analysis_backlog property #

add_file(path, file_object, printer_profile = None, links = None, allow_overwrite = False, display = None) #

add_folder(path, ignore_existing = True, display = None) #

add_link(path, rel, data) #

canonicalize(path) #

copy_file(source, destination) #

copy_folder(source, destination) #

file_exists(path) #

file_in_path(path, filepath) #

folder_exists(path) #

get_additional_metadata(path, key) #

get_metadata(path) #

has_analysis(path) #

join_path(*path) #

last_modified(path = None, recursive = False) #

list_files(path = None, filter = None, recursive = True, level = 0, force_refresh = False) #

move_file(source, destination) #

move_folder(source, destination) #

path_in_storage(path) #

path_on_disk(path) #

remove_additional_metadata(path, key) #

remove_file(path) #

remove_folder(path, recursive = True) #

remove_link(path, rel, data) #

sanitize(path) #

sanitize_name(name) #

sanitize_path(path) #

set_additional_metadata(path, key, data, overwrite = False, merge = False) #

split_path(path) #

`LocalFileStorage(basefolder, create = False, really_universal = False)` #

`sanitize(path)` #

`sanitize_name(name)` #

`sanitize_path(path)` #

`StorageInterface` #

`analysis_backlog` `property` #

`add_file(path, file_object, printer_profile = None, links = None, allow_overwrite = False, display = None)` #

`add_folder(path, ignore_existing = True, display = None)` #

`add_link(path, rel, data)` #

`canonicalize(path)` #

`copy_file(source, destination)` #

`copy_folder(source, destination)` #

`file_exists(path)` #

`file_in_path(path, filepath)` #

`folder_exists(path)` #

`get_additional_metadata(path, key)` #

`get_metadata(path)` #

`has_analysis(path)` #

`join_path(*path)` #

`last_modified(path = None, recursive = False)` #

`list_files(path = None, filter = None, recursive = True, level = 0, force_refresh = False)` #

`move_file(source, destination)` #

`move_folder(source, destination)` #

`path_in_storage(path)` #

`path_on_disk(path)` #

`remove_additional_metadata(path, key)` #

`remove_file(path)` #

`remove_folder(path, recursive = True)` #

`remove_link(path, rel, data)` #

`sanitize(path)` #

`sanitize_name(name)` #

`sanitize_path(path)` #

`set_additional_metadata(path, key, data, overwrite = False, merge = False)` #

`split_path(path)` #