Skip to content

octoprint.filemanager.storage#

LocalFileStorage #

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 :func:path_on_disk.

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

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

:param string basefolder: the path to the folder under which to create the storage :param bool create: True if the folder should be created if it doesn't exist yet, False otherwise :param bool really_universal: True if the file names should be forced to 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 that 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.

sanitize_name(name) #

Raises a :class:ValueError for a name containing / or \. Otherwise sanitizes the given name using octoprint.files.sanitize_filename. Also strips any leading ..

sanitize_path(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 :func:sanitize_name. Final path is the absolute path including leading basefolder path.

StorageInterface #

Interface of storage adapters for OctoPrint.

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

Adds the file file_object as path

:param string path: the file's new path, will be sanitized :param object file_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 :param object printer_profile: the printer profile associated with this file (if any) :param list links: any links to add with the file :param bool allow_overwrite: 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 :param unicode display: display name of the file :return: 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.

:param string path: the path of the new folder :param bool ignore_existing: if set to True, no error will be raised if the folder to be added already exists :param unicode display: display name of the folder :return: the sanitized name of the new folder to be used for future references to the folder

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.

:param path: path of the file for which to add a link :param rel: type of relation of the link to add (currently model, machinecode and web are supported) :param data: additional data of the link to add

analysis_backlog() property #

Get an iterator over all items stored in the storage that need to be analysed by the :class:~octoprint.filemanager.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.

:return: an iterator yielding all un-analysed files in the storage

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 :func:~octoprint.filemanager.StorageInterface.sanitize, which also takes care of stripping any invalid characters.

Parameters:

Name Type Description Default
path

the path to canonicalize

required

Returns:

Type Description

a 2-tuple containing the canonicalized path and file name

copy_file(source, destination) #

Copies the file source to destination

:param string source: path to the source file :param string destination: path to destination

:return: the path in the storage to the copy of the file

copy_folder(source, destination) #

Copies the folder source to destination

:param string source: path to the source folder :param string destination: path to destination

:return: the path in the storage to the copy of the folder

file_exists(path) #

Returns whether the file indicated by path exists or not. :param string path: the path to check for existence :return: True if the file exists, False otherwise

file_in_path(path, filepath) #

Returns whether the file indicated by file is inside path or not. :param string path: the path to check :param string filepath: path to the file :return: True if the file is inside the path, False otherwise

folder_exists(path) #

Returns whether the folder indicated by path exists or not. :param string path: the path to check for existence :return: True if the folder exists, False otherwise

get_additional_metadata(path, key) #

Fetches additional metadata at key from the metadata of path.

:param path: the virtual path to the file for which to fetch additional metadata :param key: key of metadata to fetch

get_metadata(path) #

Retrieves the metadata for the file path.

:param path: virtual path to the file for which to retrieve the metadata :return: the metadata associated with the file

has_analysis(path) #

Returns whether the file at path has been analysed yet

:param path: virtual path to the file for which to retrieve the metadata

join_path(*path) #

Join path elements together :param path: path elements to join :return: 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:

Name Type Description Default
path str or None

Path for which to determine the subtree's last modification date. If left out or set to None, defatuls to storage root.

None
recursive bool

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

False

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": "", "links": [ ... ], ... }, ... } "test.gcode": { "name": "test.gcode", "path": "test.gcode", "type": "machinecode", "typePath": ["machinecode", "gcode"], "hash": "", "links": [...], ... }, "test.stl": { "name": "test.stl", "path": "test.stl", "type": "model", "typePath": ["model", "stl"], "hash": "", "links": [...], ... }, ... }

:param string path: base path from which to recursively list all files, optional, if not supplied listing will start from root of base folder :param function filter: a filter that matches the files that are to be returned, may be left out in which case no filtering will take place :param bool recursive: 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. :return: a dictionary mapping entry names to entry data that represents the whole file list

move_file(source, destination) #

Moves the file source to destination

:param string source: path to the source file :param string destination: path to destination

:return: the new path in the storage to the file

move_folder(source, destination) #

Moves the folder source to destination

:param string source: path to the source folder :param string destination: path to destination

:return: the new path in the storage to the folder

path_in_storage(path) #

Retrieves the equivalent in the storage adapter for path.

Opposite of :func:path_on_disk.

:param string path: the path for which to retrieve the storage path :return: 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 :class:io.UnsupportedOperation

Opposite of :func:path_in_storage.

:param string path: the virtual path for which to retrieve the path on disk :return: the path on disk to path

remove_additional_metadata(path, key) #

Removes additional metadata under key for name on path

:param path: the virtual path to the file for which to remove the metadata under key :param key: the key 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.

:param string path: path of the file to remove

remove_folder(path, recursive=True) #

Removes the folder at path

:param string path: the path of the folder to remove :param bool recursive: 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

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

:param path: path of the file from which to remove the link :param rel: type of relation of the link to remove (currently model, machinecode and web are supported) :param data: 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.

:param string path: the path to sanitize :return: a 2-tuple containing the sanitized path and file name

sanitize_name(name) #

Sanitizes the given file name, stripping it of all invalid characters. :param string name: the file name to sanitize :return: the sanitized name

sanitize_path(path) #

Sanitizes the given folder-only path, stripping it of all invalid characters. :param string path: the path to sanitize :return: 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 name'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.

:param path: the virtual path to the file for which to add additional metadata :param key: key of metadata to add :param data: metadata to add :param overwrite: if True and key already exists, it will be overwritten :param merge: if 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. :param path: the path to split :return: a tuple (base directory, file name)

Back to top