Overview¶
Main registry¶
The class madam.core.Madam
manages the extensions that can be used to
process different file formats. It provides convenience methods to read and to
write files.
Media assets¶
At the core of MADAM are assets in the form of madam.core.Asset
objects. Asset objects are immutable and provide access the raw data via the
file-like attribute essence
and to the metadata via the dictionary
metadata
.
Processors¶
The extensions used to read, process, and write file formats are called processors. Usually, they are interfaces to external libraries that are used in the background to do all the heavy lifting. There are two types of processors in MADAM:
- Essence processors (or just processors)
- Represented by
madam.core.Processor
objects. Essence processors are responsible to read and write the actual data in a specific file format. They also offer various operations that can be performed to modify the data, e.g. to resize or to rotate an image. One implementation of this interface is themadam.image.PillowProcessor
class. - Metadata processors
- Represented by
madam.core.MetadataProcessor
objects. Metadata processors are responsible to read and write metadata only. Prominent examples of such metadata could be ID3 in MP3 audio files, or Exif in JPEG images. For example, the implementation for Exif metadata is themadam.exif.ExifMetadataProcessor
class.
Operators¶
Essence processors provide methods to modify assets, which are called operators. As operations are usually performed on many media assets, operators are implemented as partial methods that can be pre-configured and then applied to one or many assets.
Note
Operators can raise exceptions of the type
madam.core.OperatorError
if something goes wrong.
Pipelines¶
The utility class madam.core.Pipeline
makes it easy to apply a
sequence of operators to one or many assets.
portrait_pipeline = Pipeline()
portrait_pipeline.add(processor.resize(width=300, height=300, mode=ResizeMode.FIT))
portrait_pipeline.add(processor.sharpen())
for processed_asset in portrait_pipeline.process(*portrait_assets):
with open(processed_asset.filename, 'wb') as file:
file.write(processed_asset.essence.read())
Storage¶
In MADAM, media assets are organized using modular storage backends.
Backends have to subclass madam.core.AssetStorage
and behave like
Python dictionaries. It will store a media asset together with its metadata and
a set of tags using a unique key. The basic expression to store an asset would
be backend[asset_key] = asset, tags
. Here is a short explanation of the
elements in this expression:
- asset_key is a unique value. Its data type depends on the storage backend.
- The asset is an
madam.core.Asset
object with essence and metadata. - The set tags stores strings that can be used to filter assets.
Storage bakends also support filtering of assets by metadata or tags with the
methods madam.core.AssetStorage.filter()
and
madam.core.AssetStorage.filter_by_tags()
.
Note
Two basic backend implementations are provided:
madam.core.InMemoryStorage
uses a Python dictionary to store assetsmadam.core.ShelveStorage
uses Pythonshelve
module to store a serialized version of all assets and tags on disk