Root Directory Classes

Root directory

class mediafs.RootDirectory(path)

The filesystem root directory

_directoryRefresh(item)

Called whenever a directory is refreshed.

Override this in a subclass if you would like some code to be run whenever a directory is refreshed.

_fileRefresh(item)

Called whenever a file is refreshed.

Override this in a subclass if you would like some code to be run (for example, scanning the file to manipulate metadata) whenever any file is scanned.

_getDirectoryClass(path)

Returns a Python class that will be used for Directory objects in the filesystem tree.

If you want to set a new Directory class for all directories, you can just set the DirectoryClass attribute to your class. If you want to use multiple classes, you can override this method and place any logic for determining which class to use here.

_getFileClass(path)

Returns a Python class that will be used for File objects in the filesystem tree.

If you want to set a new File class for all files, you can just set the FileClass attribute to your class. If you want to use multiple classes, you can override this method and place any logic for determining which class to use here.

_getMetadataForObject(obj)

Given a FSObject, return a dict or dict-like object representing the metadata for that file or directory.

This method exists so that subclasses can override the default behavior.

_ignorePath(name, fullpath, isdir)

Based on a file or directory name and its full path, return True if a file or directory should be excluded from indexing. Otherwise return False.

_orderDirectory(contents)

From the contents argument, which is a dict with filenames as keys and File objects as values, return a list of keys that will represent the ordering of that dict.

_readMetadata()

Retrieves and returns metadata for all files in the filesystem.

The returned object should be a dict, with the keys being a unique identifier for files, and values being a dict or dict-like object containing the metadata associated with that key.

By default, keys should be the output of FSObject.hash(), but this can be changed by adding a custom implementation of RootDirectory._getMetadataForObject().

The constructor will run self._md = self._readMetadata().

Should be implemented in a subclass to allow reading in metadata from a file or database.

_readTreeData()

Reads in the directory tree from a file.

Should be implemented in a subclass to allow the contents of the filesystem to be cached.

Should return a 2-tuple, with the first element being a dict (keys are filenames, values are of type FSObject), and the second element being a list containing all keys in that dict which represents the ordering of those keys.

The constructor will run self._contents, self._order = self._readTreeData().

_writeMetadata(metadata)

The metadata argument is a dict containing metadata for the entire filesystem. The keys represent the output of FSObject.hash(), and the values are dicts containing the metadata assocated with that hash.

This method should write that metadata to a file or database so that it can be restored later with _readMetadata().

_writeTreeData(tree, ordering)

Writes out the directory tree to a file.

Should be implemented in a subclass to allow the contents of the filesystem to be cached.

Takes the root directory tree and the ordering of the keys in that tree, and writes them to a file or database so that a full rescan of the filesystem can be avoided.

save()

Write all metadata to disk.

scrubMetadata(autoRefresh=True)

Removes metadata entries for files that no longer exist. Takes a while to run and deletes data, so it must be run manually.

This method would be less useful if run using an out-of-date directory tree, so it will automatically call self.refresh(recursive=True). If you don’t want this to happen for whatever reason (maybe you just ran a refresh and don’t need a second one) then pass the argument autoRefresh=False to this method.

Root directory with caching and metadata persistance

class mediafs.CachedRootDirectory(path, metadataFile='.metadata.json', treeFile='.tree.json')

A root directory that uses the json module to cache the directory tree and metadata.

The constructor adds two optional arguments, metadataFile and treeFile. They default to .metadata.json and .tree.json, respectively, and can be used to specify the paths to the metadata storage for this filesystem.

If metadataFile=None is passed to the constructor, metadata will not be saved or restored.

If treeFile=None is passed to the constructor, the filesystem tree cache will not be saved or restored.

If metadataFile or treeFile are left at their default values, they will be created inside the root directory. Otherwise the values will be treated as paths to the metadata files, so it is up to the user to put them in a reasonable place.

Root directory that keeps itself in sync with the filesystem

Requirements:

• butter: https://pypi.python.org/pypi/butter
• Linux: The butter library is Linux-specific
• asyncio: Python 3.4+

Example:

import asyncio
from mediafs.synced import SyncedRootDirectory

loop = asyncio.get_event_loop()
fs = SyncedRootDirectory("/home/john/documents", loop)

# make sure we start perfectly in sync
fs.refresh(recursive=True)

@asyncio.coroutine
def mainloop():
    while True:
        filesystemEvents = yield from fs.processFilesystemEvents()
        for event in filesystemEvents:
            # event is a namedtuple with 3 elements
            print(event.type, event.parent, event.name)
        yield from asyncio.sleep(1)

loop.run_until_complete(mainloop())

Root directory that stores metadata in extended filesystem attributes

Requirements:

• pyxattr: https://pypi.python.org/pypi/pyxattr
• Linux: The pyxattr library is Linux-specific

Example:

from mediafs.xattrs import XAttrRootDirectory

fs = XAttrRootDirectory("/home/john/documents")
fs['file1.txt'].metadata['author'] = "John Smith"
# done! no need to call save()