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)