Improve docs for utils.py
This commit is contained in:
parent
d7045644f1
commit
845fa40ed8
|
@ -1,4 +1,4 @@
|
||||||
"""Contains various utilities that are used throughout the package."""
|
"""Various utilities that are used throughout the package."""
|
||||||
|
|
||||||
import collections
|
import collections
|
||||||
import html
|
import html
|
||||||
|
@ -31,13 +31,14 @@ class AutoStrEnum(Enum):
|
||||||
>>> Fruits.apple.value
|
>>> Fruits.apple.value
|
||||||
"apple"
|
"apple"
|
||||||
"""
|
"""
|
||||||
|
|
||||||
@staticmethod
|
@staticmethod
|
||||||
def _generate_next_value_(name, *_):
|
def _generate_next_value_(name, *_):
|
||||||
return name
|
return name
|
||||||
|
|
||||||
|
|
||||||
def dict_update_recursive(dict1: dict, dict2: dict) -> None:
|
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
|
# https://gist.github.com/angstwad/bf22d1822c38a92ec0a9
|
||||||
|
|
||||||
for k in dict2:
|
for k in dict2:
|
||||||
|
@ -49,7 +50,7 @@ def dict_update_recursive(dict1: dict, dict2: dict) -> None:
|
||||||
|
|
||||||
|
|
||||||
async def is_svg(file: File) -> bool:
|
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)]
|
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:
|
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.
|
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:
|
async def guess_mime(file: File) -> str:
|
||||||
"""Return the mime type for a file, or application/octet-stream if it
|
"""Return the file's mimetype, or `application/octet-stream` if unknown."""
|
||||||
can't be guessed.
|
|
||||||
"""
|
|
||||||
|
|
||||||
if isinstance(file, io.IOBase):
|
if isinstance(file, io.IOBase):
|
||||||
file.seek(0, 0)
|
file.seek(0, 0)
|
||||||
|
@ -114,7 +114,7 @@ async def guess_mime(file: File) -> str:
|
||||||
|
|
||||||
|
|
||||||
def plain2html(text: str) -> str:
|
def plain2html(text: str) -> str:
|
||||||
"""Transform plain text into HTML, this converts \n and \t."""
|
"""Convert `\\n` into `<br>` tags and `\\t` into four spaces."""
|
||||||
|
|
||||||
return html.escape(text)\
|
return html.escape(text)\
|
||||||
.replace("\n", "<br>")\
|
.replace("\n", "<br>")\
|
||||||
|
@ -122,10 +122,15 @@ def plain2html(text: str) -> str:
|
||||||
|
|
||||||
|
|
||||||
def serialize_value_for_qml(value: Any) -> Any:
|
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
|
Returns:
|
||||||
objects to their string version.
|
|
||||||
|
- 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):
|
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]:
|
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 {
|
return {
|
||||||
m[0]: m[1] for m in inspect.getmembers(module, inspect.isclass)
|
m[0]: m[1] for m in inspect.getmembers(module, inspect.isclass)
|
||||||
|
|
Loading…
Reference in New Issue
Block a user