Uranium
Application Framework
Loading...
Searching...
No Matches
UM.CentralFileStorage.CentralFileStorage Class Reference

Public Member Functions

None store (cls, str path, str path_id, Version version=Version("1.0.0"), bool move_file=True)
 
str retrieve (cls, str path_id, str sha256_hash, Version version=Version("1.0.0"))
 
str getCentralStorageLocation (cls)
 
None setIsEnterprise (cls, bool is_enterprise)
 

Protected Member Functions

str _getItemPath (cls, str item_id, Version version)
 
str _hashFile (cls, str file_path)
 
str _hashDirectory (cls, str directory)
 
str _hashItem (cls, str item_path)
 

Static Protected Attributes

dict _unmoved_files = {}
 
bool _is_enterprise_version = False
 

Detailed Description

This class stores and retrieves items (files or directories) stored in a location central to all versions of the
application. Its purpose is to provide a way for plug-ins to store big items (files or directories) without having
those big items copied to the new resource directory at every version upgrade.

Each items gets a path ID and a version number by which to identify the individual items. The path ID and version
number combination needs to be unique for an item and together refer to a specific item's contents. When retrieving
the item, the retriever needs to specify the hash of the item that it expects to find, and this hash is checked
before giving up the location of the item. This hash will guard against unauthorised changes to the item. The
plug-in, if properly signed, will then not be surprised by malicious content in that file or directory.

If multiple items need to be moved, it's also possible to add a file called "central_storage.json" to the root
directory of the plugin. This json needs to contain a list, of which each element is a list of 4 elements.
The first element holds the relative path to the item (file or directory), the second is the ID, the third is the
ID of the item and the last item is the hash.

A brief example of such a file:
[
    ["files/VeryLargeFileToStore.big", "very_large_file", "1.0.1", "abcdefghijklmnop"],
    ["relative/path/to/dir", "relative/path/to/dir/in/storage", "1.0.1, "124986978cb21e"]
]

Member Function Documentation

◆ _getItemPath()

str UM.CentralFileStorage.CentralFileStorage._getItemPath ( cls,
str item_id,
Version version )
protected
Get a canonical path for a hypothetical item (file or folder) with a specified ID and version.
:param item_id: The name of the item (file or directory) to get a name for.
:param version: The version number of the item (file or directory) to get a name for.
:return: A path to store such an item.

◆ _hashDirectory()

str UM.CentralFileStorage.CentralFileStorage._hashDirectory ( cls,
str directory )
protected
Returns a SHA-256 hash of the specified directory.
:param directory: The path to a directory to get the hash of.
:return: A cryptographic hash of the specified directory.

◆ _hashFile()

str UM.CentralFileStorage.CentralFileStorage._hashFile ( cls,
str file_path )
protected
Returns a SHA-256 hash of the specified file.
:param file_path: The path to a file to get the hash of.
:return: A cryptographic hash of the specified file.

◆ _hashItem()

str UM.CentralFileStorage.CentralFileStorage._hashItem ( cls,
str item_path )
protected
Calls the hash function according to the type of the path (directory or file).
:param path: The path that needs to be hashed.
:return: A cryptographic hash of the specified path.

◆ getCentralStorageLocation()

str UM.CentralFileStorage.CentralFileStorage.getCentralStorageLocation ( cls)
Gets a directory to store things in a version-neutral location.
:return: A directory to store things centrally.

◆ retrieve()

str UM.CentralFileStorage.CentralFileStorage.retrieve ( cls,
str path_id,
str sha256_hash,
Version version = Version("1.0.0") )
Retrieve the path of a previously stored item (file or directory).
:param path_id: The name of the item (file or directory) to retrieve.
:param sha256_hash: A SHA-256 hash of the item (file or directory) you expect to receive from the central storage.
:param version: The version number of the item (file or directory) to retrieve.
:return: A path to the location of the centrally stored item (file or directory).
:raises FileNotFoundError: There is no item (file or directory) stored with that name and version.
:raises IOError: The hash of the item (file or directory) is incorrect. Opening this item could be a security
risk.

◆ store()

None UM.CentralFileStorage.CentralFileStorage.store ( cls,
str path,
str path_id,
Version version = Version("1.0.0"),
bool move_file = True )
Store a new item (file or directory) into the central file storage. This item will get moved to a storage
location that is not specific to this version of the application.

If the item already exists, this will check if it's the same item. If the item is not the same, it raises a
`FileExistsError`. If the item is the same, no error is raised and the item to store is simply deleted. It is a
duplicate of the item already stored.

Note that this function SHOULD NOT be called by plugins themselves. The central_storage.json should be used
instead!

:param path: The path to the item (file or directory) to store in the central file storage.
:param path_id: A name for the item (file or directory) to store.
:param version: A version number for the item (file or directory).
:param move_file: Should the file be moved at all or just remembered for later retrieval
:raises FileExistsError: There is already a centrally stored item (file or directory) with that name and
version, but it's different.

The documentation for this class was generated from the following file: