diff --git a/src/backend/utils.py b/src/backend/utils.py
index d5a68ffe..87c88416 100644
--- a/src/backend/utils.py
+++ b/src/backend/utils.py
@@ -1,4 +1,4 @@
-"""Contains various utilities that are used throughout the package."""
+"""Various utilities that are used throughout the package."""
import collections
import html
@@ -31,13 +31,14 @@ class AutoStrEnum(Enum):
>>> Fruits.apple.value
"apple"
"""
+
@staticmethod
def _generate_next_value_(name, *_):
return name
def dict_update_recursive(dict1: dict, dict2: dict) -> None:
- """Recursive version of dict.update()."""
+ """Deep-merge `dict1` and `dict2`, recursive version of `dict.update()`."""
# https://gist.github.com/angstwad/bf22d1822c38a92ec0a9
for k in dict2:
@@ -49,7 +50,7 @@ def dict_update_recursive(dict1: dict, dict2: dict) -> None:
async def is_svg(file: File) -> bool:
- """Return True if the file is a SVG. Uses lxml for detection."""
+ """Return whether the file is a SVG (`lxml` is used for detection)."""
chunks = [c async for c in async_generator_from_data(file)]
@@ -62,7 +63,8 @@ async def is_svg(file: File) -> bool:
async def svg_dimensions(file: File) -> Size:
- """Return the width & height or viewBox width & height for a SVG.
+ """Return the width and height, or viewBox width and height for a SVG.
+
If these properties are missing (broken file), ``(256, 256)`` is returned.
"""
@@ -85,9 +87,7 @@ async def svg_dimensions(file: File) -> Size:
async def guess_mime(file: File) -> str:
- """Return the mime type for a file, or application/octet-stream if it
- can't be guessed.
- """
+ """Return the file's mimetype, or `application/octet-stream` if unknown."""
if isinstance(file, io.IOBase):
file.seek(0, 0)
@@ -114,7 +114,7 @@ async def guess_mime(file: File) -> str:
def plain2html(text: str) -> str:
- """Transform plain text into HTML, this converts \n and \t."""
+ """Convert `\\n` into `
` tags and `\\t` into four spaces."""
return html.escape(text)\
.replace("\n", "
")\
@@ -122,10 +122,15 @@ def plain2html(text: str) -> str:
def serialize_value_for_qml(value: Any) -> Any:
- """Transform a value to make it easier to use from QML.
+ """Convert a value to make it easier to use from QML.
- Currently, this transforms Enum members to their actual value and Path
- objects to their string version.
+ Returns:
+
+ - Return the member's actual value for `Enum` members
+ - A `file://...` string for `Path` objects
+ - Strings for `UUID` objects
+ - A number of milliseconds for `datetime.timedelta` objects
+ - The class `__name__` for class types.
"""
if hasattr(value, "__class__") and issubclass(value.__class__, Enum):
@@ -147,7 +152,7 @@ def serialize_value_for_qml(value: Any) -> Any:
def classes_defined_in(module: ModuleType) -> Dict[str, Type]:
- """Return a {name: class} dict of all the classes a module defines."""
+ """Return a `{name: class}` dict of all the classes a module defines."""
return {
m[0]: m[1] for m in inspect.getmembers(module, inspect.isclass)