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

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.

class octoprint.filemanager.analysis.AnalysisQueue

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

At the moment, only the analysis of GCODE files for 3D printing is supported, through GcodeAnalysisQueue.

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 minutes
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³
class octoprint.filemanager.analysis.QueueEntry

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.

octoprint.filemanager.destinations

octoprint.filemanager.storage

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)

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 (unicode) – display name of the file
Returns:

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 (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 (unicode) – display name of the folder
Returns:

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.

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

Copys 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)

Copys 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_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
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)

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
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 and error will be raised if the folder is not empty (apart from .metadata.yaml) when it’s to be removed

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)

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

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

Metadata is managed inside .metadata.yaml 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().

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 slugifies the given name by converting it to ASCII, leaving -, _, ., (, and ) as is.

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.

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)

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

Parameters:path (str) – The absolute path to where to save 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.
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.

Parameters:input_stream (io.IOBase) – The stream to process on the fly.
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 (str) – The line as read from self.input_stream
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:str or None
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 (io.IOBase) – One or more streams to concatenate.
class octoprint.filemanager.util.StreamWrapper(filename, *streams)

A wrapper allowing processing of one or more consecutive streams.

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

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.