MediaManager Reference Guide
This guide is for versions Beta 47+
Source code
Background Information:
A Technology Stack on Top of a (Neo4j) Graph Database
Helper library for the management of media files (documents and images)
Static class that doesn't get instantiated;
however, it must be initialized with calls to set_media_folder() and set_default_folders()
| name | arguments | returns |
|---|---|---|
| set_media_folder | path_name: str | None |
:param path_name: Location where the media for Content Items is stored, including the final "/"
EXAMPLE on Windows: "D:/media/"
(notice the forward slashes, even on Windows)
:return: None
|
||
| name | arguments | returns |
|---|---|---|
| set_default_folders | folder_dict :dict | None |
:param folder_dict:
:return:
|
||
| name | arguments | returns |
|---|---|---|
| default_file_path | class_name :str, thumb=False | str |
Return the default file path, including the final "/", of the media files associated to the given schema Class
:param class_name: The name of the Class of the media item of interest
:param thumb: If True, then the "thumbnail" version is returned
(only applicable to some media types, such as images)
:return: The full file path, including the final "/"
EXAMPLES on Windows:
"D:/media/documents/"
"D:/media/images/resized/"
|
||
| name | arguments | returns |
|---|---|---|
| retrieve_full_path | uri :str, thumb=False | str |
Return the full path for the specified media file or, if requested, for its thumbnail image.
Includes the final "/"
EXAMPLE (on Windows): "D:/BACKUP_media/images/resized/"
:param uri: Unique identifier string for the Media Item of Interest
:param thumb: If True, return the folder for the thumbnail image instead
:return: EXAMPLES on Windows:
"D:/media/documents/"
"D:/media/images/resized/"
|
||
| name | arguments | returns |
|---|---|---|
| lookup_media_file | uri :str, thumb=False | (str, str, str) |
:param uri: Unique identifier for the Media Item of Interest
:param thumb: If True, return the folder for the thumbnail image instead;
ignored if the file suffix is "svg" (regardless of case),
because SVG files cannot be resized
:return: The triplet (filepath, basename, suffix)
Notes: filepath ends with a "/"
the basename is exclusive of path and of suffix
the suffix does NOT include the dot
EXAMPLE:
("D:/media/my_media_folder/images/", "snap1", "jpg")
|
||
| name | arguments | returns |
|---|---|---|
| get_full_filename | uri : str, thumb=False | str |
:param uri: Unique identifier for the Media Item of Interest
:param thumb: If True, return the folder for the thumbnail image instead;
ignored if the file suffix is "svg" (regardless of case),
because SVG files cannot be resized
:return: EXAMPLE: "D:/media/my_media_folder/images/Tahiti vacation/"
|
||
| name | arguments | returns |
|---|---|---|
| get_from_text_file | filename: str, path="", encoding="latin-1" | str |
Read in and return the contents of the specified TEXT file.
Note: 'utf8' encoding at times led to problems.
More info: https://stackoverflow.com/questions/5552555/unicodedecodeerror-invalid-continuation-byte
:param filename: FULL filename, INCLUDING path - unless path is passed in the following argument
EXAMPLE on Windows:
"D:/media/my_file.txt" (notice the forward slashes, even on Windows)
:param path: [OPTIONAL] String to prefix to the filename argument, above
:param encoding: A string such as "latin-1" (aka "iso-8859-1") or "utf8"
:return: The contents of the text file, using the requested encoding
|
||
| name | arguments | returns |
|---|---|---|
| get_from_binary_file | path: str, filename: str | bytes |
Read in and return the contents of the specified BINARY file
:param path: String that must include a final "/", containing the full path of the file
EXAMPLE on Windows: "D:/media/" (notice the forward slashes, even on Windows)
:param filename: EXCLUSIVE of path. EXAMPLE: "my pic.jpg"
:return: The contents of the binary file
|
||
| name | arguments | returns |
|---|---|---|
| get_binary_content | uri :str, th | (str, bytes) |
Fetch and return the contents of a media item stored in a local file.
In case of error, raise an Exception
:param uri: String identifier for a media item
:param th: If not None, then the thumbnail version is returned (only
applicable to images).
If the thumbnail version is not found, but the full-size image
is present, create and save a thumbnail file, prior to
returning the contents of the newly-created file
:return: The pair (filename suffix, binary data in the file)
|
||
| name | arguments | returns |
|---|---|---|
| before_update_content | uri :str, set_dict :dict, class_name :str | None |
Invoked before a Media Item of this type gets updated in the database
:param uri: Unique identifier for the Media Item of Interest
:param set_dict: A dict of field values to eventually set into the database
:param class_name: (Redundant, since implied by the uri)
:return: None
|
||
| name | arguments | returns |
|---|---|---|
| save_into_file | contents: str, filename: str, class_name :str | None |
Save the given data into the specified file in the class-wide media folder. UTF8 encoding is used.
In case of error, detailed Exceptions are raised
:param contents: String to store into the file
:param filename: EXCLUSIVE of file path
:param class_name: Needed to determine the default folder location (which is based on class_name)
:return: None. In case of errors, detailed Exceptions are raised
|
||
| name | arguments | returns |
|---|---|---|
| delete_media_file | uri: str, thumb=False | bool |
Delete the specified media file, assumed in a standard location
:param uri: Unique identifier for the Media Item of Interest
:param thumb: If True, then the "thumbnail" version is deleted
(only applicable to some media types, such as images)
:return: True if successful, or False otherwise
|
||
| name | arguments | returns |
|---|---|---|
| delete_file | fullname: str | bool |
Delete the specified file
:param fullname: Full name of the file to delete, including its path
:return: True if successful, or False if file was not found
|
||
| name | arguments | returns |
|---|---|---|
| move_file | src: str, dest: str | None |
Rename (move) the specified file.
An Exception is raised if the file was not found,
or if another file with new name already exists
:param src: Old full name (incl. path) of the file to rename
:param dest: New full name (incl. path) of the file to rename
:return: None
|
||
| name | arguments | returns |
|---|---|---|
| check_file_name | filename :str | str |
Check the given filename against a list of acceptable filename characters, based on a slightly-expanded
(but still conservative) version of the POSIX portable file name character set
https://www.ibm.com/docs/en/zos/3.1.0?topic=locales-posix-portable-file-name-character-set
:return: The first non-allowed character, if applicable;
if all characters are good, return ""
|
||
| name | arguments | returns |
|---|---|---|
| get_mime_type | suffix :str | str |
Return the appropriate MIME type for file content type assumed from the
filename extension, assuming normal conventions are being followed
:param suffix: A string with a filename's suffix (i.e. the "file extension type".)
EXAMPLES: "jpg" or "PDF"
:return: A string describing the MIME type for files of that particular type
|
||
Utility class for managing images, especially in the context of uploads.
SIDE NOTE: The "th" format from the Classic BrainAnnex, is:
"default (largish) thumbs - 3 fit in a row" : width sized to 300
formats =
{
"th": { "description": "default (largish) thumbs - 3 fit in a row",
"size": 300,
"affected": "w"
}
}
| name | arguments | returns |
|---|---|---|
| save_thumbnail | src_folder: str, filename: str, save_to_folder: str, src_width: int, src_height: int | None |
Make a thumbnail of the specified image, and save it in a file.
The "th" thumbnail format is being followed.
:param src_folder: Full path of folder with the file to resize. It MUST end with "/"
EXAMPLE (on Windows): "D:/Docs/Brain Annex/media/"
:param filename: Name of file to resize. EXAMPLE: "my image.jpg"
:param save_to_folder: Full path of folder where to save the resized file. It MUST end with "/"
EXAMPLE (on Windows): "D:/Docs/Brain Annex/media/resized/"
:param src_width: Pixel width of the original image
:param src_height: Pixel height of the original image
:return: None. In case of error, an Exception is raised
|
||
| name | arguments | returns |
|---|---|---|
| scale_down_horiz | src_folder: str, filename: str, save_to_folder: str, src_width: int, src_height: int, target_width: int | None |
Resize an image to the target WIDTH, and save it in a file.
:param src_folder: Full path of folder with the file to resize. It MUST end with "/"
EXAMPLE (on Windows): "D:/Docs/Brain Annex/media/"
:param filename: Name of file to resize. EXAMPLE: "my image.jpg"
:param save_to_folder: Full path of folder where to save the resized file. It MUST end with "/"
EXAMPLE (on Windows): "D:/Docs/Brain Annex/media/resized/"
:param src_width: Pixel width of the original image
:param src_height: Pixel height of the original image
:param target_width: Desired pixel width of the resized image
:return: None. In case of error, an Exception is raised
|
||
| name | arguments | returns |
|---|---|---|
| get_image_size | source_full_name | (int, int) |
Return the size of the given image.
:param source_full_name: EXAMPLE (on Windows): "D:/Docs/Brain Annex/media/resized/my image.jpg"
:return: The pair (width, height) with the image dimensions in pixels. In case of error, an Exception is raised
|
||
| name | arguments | returns |
|---|---|---|
| process_uploaded_image | media_folder :str, basename :str, suffix :str | dict |
If possible, obtain the size of the image, resize it to a thumbnail,
save the thumbnail in the "resized/" subfolder of the specified media folder;
not all images (such as SVG's) can be resized.
Return a dictionary of additional image-specific properties that will go in the database.
:param media_folder:Name of the folder (including the final "/") where the media files are located.
The resized version will go in a "resized" subfolder of it.
EXAMPLE (on Windows): "D:/Docs/media/
:param basename: EXAMPLE: "my image"
:param suffix: EXAMPLE: "jpg" . It's ok to be an empty string
:return: A dictionary of extra properties to store in database, containing some or all of
the following keys: "caption", "width", "height"
|
||
| name | arguments | returns |
|---|---|---|
| describe_image | source_full_name | None |
Print out some info about the given image:
the file format, the pixel format, the image size and (if any) the color palette
:param source_full_name: EXAMPLE (on Windows): "D:/Docs/media/resized/my image.jpg"
:return: None. In case of error, an Exception is raised
|
||