Introduction to MediaFS

MediaFS is a Python library that makes it easy to search and manage a directory tree. It has support for custom metadata as well as caching for faster searching.

The primary design goal for MediaFS is to be a backend for managing media collections, such as for music or video, but the implementation is filetype-agnostic and can be used for working with any type of data.

Simple Examples

from mediafs import RootDirectory

fs = RootDirectory("/some/directory")

# prints number of top-level files and directories
print(len(fs))

# prints file size of a file in bytes
print(fs['some_file.txt'].size)

Iterating over files and directories

There are a few ways to iterate over files and directories. The primary way is with Directory.all(). This is a generator function, so if you want to assign the results of it to a variable, you’ll need to wrap it in a call to list().

items = fs.all() # won't work :(
items = list(fs.all()) # works :)

all() takes several arguments - recursive, reverse, dirs, and files, all of which are optional arguments, and all of which take boolean values.

• recursive: If True, will iterate recursively. If False, will just give top-level items. (defaults to False)
• reverse: If True, will reverse the item order. (defaults to False)
• dirs: If True, will return directories. If False, will not return directories. (defaults to True)
• files: If True, will return files. If False, will not return files. (defaults to True)

# print the names of all top-level files and directories
for item in fs.all():
    print(item.name)

# print the names of every file and directory
for item in fs.all(recursive=True):
    print(item.name)

# print the names of every directory
for item in fs.all(recursive=True, files=False):
    print(item.name)

# print the names of every file
for item in fs.all(recursive=True, dirs=False):
    print(item.name)

Because filter(), search(), and query() all use all() under the hood, they each take recursive, dirs, and files arguments and pass them directly to all(). This means that when searching, the semantics of these three arguments are the same across all four methods.