octoprint.filemanager

class octoprint.filemanager.ContentTypeDetector(extensions, detector)

detector: Alias for field number 1

extensions: Alias for field number 0

class octoprint.filemanager.ContentTypeMapping(extensions, content_type)

content_type: Alias for field number 1

extensions: Alias for field number 0

exception octoprint.filemanager.NoSuchStorage

octoprint.filemanager.analysis

class octoprint.filemanager.analysis.AbstractAnalysisQueue(finished_callback)

The AbstractAnalysisQueue is the parent class of all specific analysis queues such as the GcodeAnalysisQueue. It offers methods to enqueue new entries to analyze and pausing and resuming analysis processing.

Parameters:: finished_callback (callable) – Callback that will be called upon finishing analysis of an entry in the queue. The callback will be called with the analyzed entry as the first argument and the analysis result as returned from the queue implementation as the second parameter.

_do_analysis(high_priority=False)

Performs the actual analysis of the current entry which can be accessed via self._current. Needs to be overridden by sub classes.

Parameters:

high_priority (bool) – Whether the current entry has high priority or not.

Returns:

The result of the analysis which will be forwarded to the finished_callback provided during: construction.

Return type:

object

_do_abort(reenqueue=True): Aborts analysis of the current entry. Needs to be overridden by sub classes.

enqueue(entry, high_priority=False)

Enqueues an entry for analysis by the queue.

If high_priority is True (defaults to False), the entry will be prioritized and hence processed before other entries in the queue with normal priority.

Parameters:

entry (QueueEntry) – The QueueEntry to analyze.
high_priority (boolean) – Whether to process the provided entry with high priority (True) or not (False, default)

pause(): Pauses processing of the queue, e.g. when a print is active.

resume(): Resumes processing of the queue, e.g. when a print has finished.

exception octoprint.filemanager.analysis.AnalysisAborted(reenqueue=True, *args, **kwargs)

class octoprint.filemanager.analysis.AnalysisQueue(queue_factories)

OctoPrint’s AnalysisQueue can manage various AbstractAnalysisQueue implementations, mapped by their machine code type.

By invoking register_finish_callback() it is possible to register oneself as a callback to be invoked each time the analysis of a queue entry finishes. The call parameters will be the finished queue entry as the first and the analysis result as the second parameter. It is also possible to remove the registration again by invoking unregister_finish_callback().

enqueue() allows enqueuing QueueEntry instances to analyze. If the QueueEntry.type is unknown (no specific child class of AbstractAnalysisQueue is registered for it), nothing will happen. Otherwise the entry will be enqueued with the type specific analysis queue.

class octoprint.filemanager.analysis.GcodeAnalysisQueue(finished_callback)

A queue to analyze GCODE files. Analysis results are dict instances structured as follows:

Key	Description
`estimatedPrintTime`	Estimated time the file take to print, in seconds
`filament`	Substructure describing estimated filament usage. Keys are `tool0` for the first extruder, `tool1` for the second and so on. For each tool extruded length and volume (based on diameter) are provided.
`filament.toolX.length`	The extruded length in mm
`filament.toolX.volume`	The extruded volume in cm³
`printingArea`	Bounding box of the printed object in the print volume (minimum and maximum coordinates)
`printingArea.minX`	Minimum X coordinate of the printed object
`printingArea.maxX`	Maximum X coordinate of the printed object
`printingArea.minY`	Minimum Y coordinate of the printed object
`printingArea.maxY`	Maximum Y coordinate of the printed object
`printingArea.minZ`	Minimum Z coordinate of the printed object
`printingArea.maxZ`	Maximum Z coordinate of the printed object
`dimensions`	Dimensions of the printed object in X, Y, Z
`dimensions.width`	Width of the printed model along the X axis, in mm
`dimensions.depth`	Depth of the printed model along the Y axis, in mm
`dimensions.height`	Height of the printed model along the Z axis, in mm
`travelArea`	Bounding box of all machine movements (minimum and maximum coordinates)
`travelArea.minX`	Minimum X coordinate of the machine movement
`travelArea.maxX`	Maximum X coordinate of the machine movement
`travelArea.minY`	Minimum Y coordinate of the machine movement
`travelArea.maxY`	Maximum Y coordinate of the machine movement
`travelArea.minZ`	Minimum Z coordinate of the machine movement
`travelArea.maxZ`	Maximum Z coordinate of the machine movement
`travelDimensions`	Dimensions of the travel area in X, Y, Z
`travelDimensions.width`	Width of the travel area along the X axis, in mm
`travelDimensions.depth`	Depth of the travel area along the Y axis, in mm
`travelDimensions.height`	Height of the travel area along the Z axis, in mm

class octoprint.filemanager.analysis.QueueEntry(name, path, type, location, absolute_path, printer_profile, analysis)

A QueueEntry for processing through the AnalysisQueue. Wraps the entry’s properties necessary for processing.

Parameters:

name (str) – Name of the file to analyze.
path (str) – Storage location specific path to the file to analyze.
type (str) – Type of file to analyze, necessary to map to the correct AbstractAnalysisQueue sub class. At the moment, only gcode is supported here.
location (str) – Location the file is located on.
absolute_path (str) – Absolute path on disk through which to access the file.
printer_profile (PrinterProfile) – PrinterProfile which to use for analysis.
analysis (dict) – GcodeAnalysisQueue results from prior analysis, or None if there is none.

octoprint.filemanager.destinations

octoprint.filemanager.storage

class octoprint.filemanager.storage.LocalFileStorage(basefolder, create=False, really_universal=False)

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().

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

Adds the file file_object as path

Parameters:

path (string) – the file’s new path, 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
user (str) – user who added the file, if known

Returns:

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

add_folder(path, ignore_existing=True, display=None, user=None)

Adds a folder as path

The path will be sanitized.

Parameters:

path (string) – 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
user (str) – user who created the folder, if known

Returns:

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 – path of the file for which to add a link
rel – type of relation of the link to add (currently model, machinecode and web are supported)
data – additional data of the link to add

property analysis_backlog

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:: 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 sanitize(), which also takes care of stripping any invalid characters.

Parameters:: path – the path to canonicalize
Returns:: a 2-tuple containing the canonicalized path and file name

copy_file(source, destination)

Copies the file source to destination

Parameters:

source (string) – path to the source file
destination (string) – path to destination

Returns:

the path in the storage to the copy of the file

copy_folder(source, destination)

Copies the folder source to destination

Parameters:

source (string) – path to the source folder
destination (string) – path to destination

Returns:

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.

Parameters:

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

get_lastmodified(path: str | None = None, recursive: bool = False) → int

Get the modification date of the specified path or path’s subtree.

Parameters:

path (str or None) – Path for which to determine the modification date. If left our 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).

get_metadata(path)

Retrieves the metadata for the file path.

Parameters:: path – virtual path to the file for which to retrieve the metadata
Returns:: the metadata associated with the file

get_size(path=None, recursive=False)

Get the size of the specified path or path’s subtree.

Parameters:

path (str or None) – Path for which to determine the subtree’s size. If left out or set to None, defaults to storage root.
recursive (bool) – Whether to determine only the size of the specified path (False, default) or the whole path’s subtree (True).

has_analysis(path)

Returns whether the file at path has been analysed yet

Parameters:: 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:

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.
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 (string) – 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:

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

move_file(source, destination, allow_overwrite=False)

Moves the file source to destination

Parameters:

source (string) – path to the source file
destination (string) – path to destination

Returns:

the new path in the storage to the file

move_folder(source, destination)

Moves the folder source to destination

Parameters:

source (string) – path to the source folder
destination (string) – path to destination

Returns:

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 (string) – the path for which to retrieve the storage path
Returns:: 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 (string) – the virtual path for which to retrieve the path on disk
Returns:: the path on disk to path

remove_additional_metadata(path, key)

Removes additional metadata under key for name on path

Parameters:

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

Parameters:: path (string) – path of the file to remove

remove_folder(path, recursive=True)

Removes the folder at path

Parameters:

path (string) – 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 name on path.

Parameters:

path – path of the file from which to remove the link
rel – type of relation of the link to remove (currently model, machinecode and web are supported)
data – additional data of the link to remove, must match existing link

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

Parameters:

path – the virtual path to the file for which to add additional metadata
key – key of metadata to add
data – metadata to add
overwrite – if True and key already exists, it will be overwritten
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)

class octoprint.filemanager.storage.StorageInterface

Interface of storage adapters for OctoPrint.

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

Adds the file file_object as path

Parameters:

path (string) – the file’s new path, 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
user (str) – user who added the file, if known

Returns:

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

add_folder(path, ignore_existing=True, display=None, user=None)

Adds a folder as path

The path will be sanitized.

Parameters:

path (string) – 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
user (str) – user who created the folder, if known

Returns:

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 – path of the file for which to add a link
rel – type of relation of the link to add (currently model, machinecode and web are supported)
data – additional data of the link to add

property analysis_backlog

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:: 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 sanitize(), which also takes care of stripping any invalid characters.

Parameters:: path – the path to canonicalize
Returns:: a 2-tuple containing the canonicalized path and file name

copy_file(source, destination)

Copies the file source to destination

Parameters:

source (string) – path to the source file
destination (string) – path to destination

Returns:

the path in the storage to the copy of the file

copy_folder(source, destination)

Copies the folder source to destination

Parameters:

source (string) – path to the source folder
destination (string) – path to destination

Returns:

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.

Parameters:

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

get_lastmodified(path: str | None = None, recursive: bool = False) → int

Get the modification date of the specified path or path’s subtree.

Parameters:

path (str or None) – Path for which to determine the modification date. If left our 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).

get_metadata(path)

Retrieves the metadata for the file path.

Parameters:: path – virtual path to the file for which to retrieve the metadata
Returns:: the metadata associated with the file

get_size(path=None, recursive=False) → int

Get the size of the specified path or path’s subtree.

Parameters:

path (str or None) – Path for which to determine the subtree’s size. If left out or set to None, defaults to storage root.
recursive (bool) – Whether to determine only the size of the specified path (False, default) or the whole path’s subtree (True).

has_analysis(path)

Returns whether the file at path has been analysed yet

Parameters:: 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:

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.
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 (string) – 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:

a 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 (string) – path to the source file
destination (string) – path to destination

Returns:

the new path in the storage to the file

move_folder(source, destination)

Moves the folder source to destination

Parameters:

source (string) – path to the source folder
destination (string) – path to destination

Returns:

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 (string) – the path for which to retrieve the storage path
Returns:: 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 (string) – the virtual path for which to retrieve the path on disk
Returns:: the path on disk to path

remove_additional_metadata(path, key)

Removes additional metadata under key for name on path

Parameters:

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

Parameters:: path (string) – path of the file to remove

remove_folder(path, recursive=True)

Removes the folder at path

Parameters:

path (string) – 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 name on path.

Parameters:

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

Parameters:: path (string) – the path to sanitize
Returns:: 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.

Parameters:

path – the virtual path to the file for which to add additional metadata
key – key of metadata to add
data – metadata to add
overwrite – if True and key already exists, it will be overwritten
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)

octoprint.filemanager.util

class octoprint.filemanager.util.AbstractFileWrapper(filename)

Wrapper for file representations to save to storages.

Parameters:: filename (str) – The file’s name

save(path, permissions=None)

Saves the file’s content to the given absolute path.

Parameters:

path (str) – The absolute path to where to save the file
permissions (int) – The permissions to set on the file

stream()

Returns a Python stream object (subclass of io.IOBase) representing the file’s contents.

Returns:: The file’s contents as a stream.
Return type:: io.IOBase

class octoprint.filemanager.util.DiskFileWrapper(filename, path, move=True)

An implementation of AbstractFileWrapper that wraps an actual file on disk. The save implementations will either copy the file to the new path (preserving file attributes) or – if move is True (the default) – move the file.

Parameters:

filename (str) – The file’s name
path (str) – The file’s absolute path
move (boolean) – Whether to move the file upon saving (True, default) or copying.

save(path, permissions=None)

Saves the file’s content to the given absolute path.

Parameters:

path (str) – The absolute path to where to save the file
permissions (int) – The permissions to set on the file

stream()

Returns a Python stream object (subclass of io.IOBase) representing the file’s contents.

Returns:: The file’s contents as a stream.
Return type:: io.IOBase

class octoprint.filemanager.util.LineProcessorStream(input_stream)

While reading from this stream the provided input_stream is read line by line, calling the (overridable) method process_line() for each read line.

Sub classes can thus modify the contents of the input_stream in line, while it is being read. Keep in mind that process_line will receive the line as a byte stream - if underlying code needs to operate on unicode you’ll need to do the decoding yourself.

Parameters:: input_stream (io.RawIOBase) – The stream to process on the fly.

close()

Flush and close the IO object.

This method has no effect if the file is already closed.

process_line(line)

Called from the read Method of this stream with each line read from self.input_stream.

By returning None the line will not be returned from the read stream, effectively being stripped from the wrapper input_stream.

Parameters:

line (bytes) – The line as read from self.input_stream in byte representation

Returns:

The processed version of the line (might also be multiple lines), or None if the line is to be: stripped from the processed stream.

Return type:

bytes or None

readable(*args, **kwargs)

Return whether object was opened for reading.

If False, read() will raise OSError.

seekable(*args, **kwargs)

Return whether object supports random access.

If False, seek(), tell() and truncate() will raise OSError. This method may need to do a test seek().

writable(*args, **kwargs)

Return whether object was opened for writing.

If False, write() will raise OSError.

class octoprint.filemanager.util.MultiStream(*streams)

A stream implementation which when read reads from multiple streams, one after the other, basically concatenating their contents in the order they are provided to the constructor.

Parameters:: *streams – One or more io.IOBase streams to concatenate.

close()

Flush and close the IO object.

This method has no effect if the file is already closed.

readable(*args, **kwargs)

Return whether object was opened for reading.

If False, read() will raise OSError.

seekable(*args, **kwargs)

Return whether object supports random access.

If False, seek(), tell() and truncate() will raise OSError. This method may need to do a test seek().

writable(*args, **kwargs)

Return whether object was opened for writing.

If False, write() will raise OSError.

class octoprint.filemanager.util.StreamWrapper(filename, *streams)

A wrapper allowing processing of one or more consecutive streams.

Parameters:: *streams – One or more io.IOBase streams to process one after another to save to storage.

save(path, permissions=None): Will dump the contents of all streams provided during construction into the target file, in the order they were provided.

stream(): If more than one stream was provided to the constructor, will return a MultiStream wrapping all provided streams in the order they were provided, else the first and only stream is returned directly.