Attachments¶

AudioAttachment ¶

Bases: BaseAttachment

Represents an audio attachment.

duration `property` `writable` ¶

duration: Optional[int]

The duration of this audio in milliseconds

from_file `async` `classmethod` ¶

from_file(
    file: Union[str, BytesIO, Path],
    file_name: Optional[str] = None,
    duration: Optional[int] = None,
) -> AudioAttachment

Generates an audio attachment

Parameters:

Name	Type	Description	Default
`file`	`Union[str, BytesIO, Path]`	The file to upload	required
`file_name`	`Optional[str]`	The name of the file (only used if file is a `BytesIO`)	`None`
`duration`	`Optional[int]`	The duration of the audio, in seconds	`None`

Returns:

Type	Description
`AudioAttachment`	An audio attachment

get_metadata `async` `classmethod` ¶

get_metadata(file: Union[str, Path]) -> Dict[str, Any]

Get metadata about an audio file.

Parameters:

Name	Type	Description	Default
`file`	`Union[str, Path]`	The audio file to get metadata for	required

Returns:

Type	Description
`Dict[str, Any]`	The metadata

AttachmentType ¶

Bases: Enum

Enumeration containing the different types of media.

Attributes:

Name	Type	Description
`FILE`	`AttachmentType`	A generic file.
`AUDIO`	`AttachmentType`	An audio file.
`VIDEO`	`AttachmentType`	A video file.
`IMAGE`	`AttachmentType`	An image file.

BaseAttachment ¶

Bases: ABC

Base class for attachments

Note

If you pass a custom file_name, this is only actually used if you pass a io.BytesIO to file. If you pass a [Path][] or a string, the file name will be resolved from the path, overriding the file_name parameter.

Parameters:

Name	Type	Description	Default
`file`	`Union[str, BytesIO, PathLike, Path]`	The file path or BytesIO object to upload.	required
`file_name`	`Optional[str]`	The name of the file. Must be specified if uploading a BytesIO object.	`None`
`mime_type`	`Optional[str]`	The mime type of the file. If not specified, it will be detected.	`None`
`size_bytes`	`Optional[int]`	The size of the file in bytes. If not specified, it will be detected.	`None`
`attachment_type`	`AttachmentType`	The type of attachment. Defaults to `AttachmentType.FILE`.	`FILE`

Attributes:

Name	Type	Description
`file`	`Union[Path, BytesIO]`	The file path or BytesIO object to upload. Resolved to a [Path][] object if a string is passed to `__init__`.
`file_name`	`str`	The name of the file. If `file` was a string or `Path`, this will be the name of the file.
`mime_type`	`str`	The mime type of the file.
`size`	`int`	The size of the file in bytes.
`type`	`AttachmentType`	The type of attachment.
`url`	`Optional[str]`	The URL of the uploaded file. This is set after the file is uploaded.
`keys`	`Optional[dict[str, str]]`	The encryption keys for the file. This is set after the file is uploaded.

size_bytes `property` ¶

size_bytes: int

Returns the size of this attachment in bytes.

as_body ¶

as_body(body: Optional[str] = None) -> dict

Generates the body for the attachment for sending. The attachment must've been uploaded first.

Parameters:

Name	Type	Description	Default
`body`	`Optional[str]`	The body to use (should be a textual description). Defaults to the file name.	`None`

Returns:

Type	Description
`dict`

from_file `async` `classmethod` ¶

from_file(
    file: Union[str, BytesIO, Path],
    file_name: Optional[str] = None,
) -> BaseAttachment

Creates an attachment from a file.

You should use this method instead of the constructor, as it will automatically detect all other values

Parameters:

Name	Type	Description	Default
`file`	`Union[str, BytesIO, Path]`	The file or BytesIO to attach	required
`file_name`	`Optional[str]`	The name of the BytesIO file, if applicable	`None`

Returns:

Type	Description
`BaseAttachment`	Loaded attachment.

from_mxc `async` `classmethod` ¶

from_mxc(client, url: str) -> BaseAttachment

Creates an attachment from an MXC URL.

Parameters:

Name	Type	Description	Default
`client`		The current client instance (used to download the attachment)	required
`url`	`str`	The MXC:// url to download	required

Returns:

Type	Description
`BaseAttachment`	The downloaded and probed attachment.

from_http `async` `classmethod` ¶

from_http(
    url: str, client_session: Optional[ClientSession] = None
) -> BaseAttachment

Creates an attachment from an HTTP URL.

This is not necessarily just for images, video, or other media - it can be used for any HTTP resource.

Parameters:

Name	Type	Description	Default
`url`	`str`	The http/s URL to download	required
`client_session`	`Optional[ClientSession]`	The aiohttp client session to use. If not specified, a new one will be created.	`None`

Returns:

Type	Description
`BaseAttachment`	The downloaded and probed attachment.

Raises:

Type	Description
`niobot.MediaDownloadException`	if the download failed.
`aiohttp.ClientError`	if the download failed.
`niobot.MediaDetectionException`	if the MIME type could not be detected.

size_as ¶

size_as(
    unit: Literal[
        "b", "kb", "kib", "mb", "mib", "gb", "gib"
    ]
) -> Union[int, float]

Helper function to convert the size of this attachment into a different unit.

Remember:

1 kilobyte (KB) is 1000 bytes
1 kibibyte (KiB) is 1024 bytes

Parameters:

Name	Type	Description	Default
`unit`	`Literal['b', 'kb', 'kib', 'mb', 'mib', 'gb', 'gib']`	The unit to convert into	required

Returns:

Type	Description
`Union[int, float]`	The converted size

upload `async` ¶

upload(client, encrypted: bool = False) -> Self

Uploads the file to matrix.

Parameters:

Name	Type	Description	Default
`client`		The client to upload	required
`encrypted`	`bool`	Whether to encrypt the attachment or not	`False`

Returns:

Type	Description
`Self`	The attachment

get_metadata `abstractmethod` `async` `classmethod` ¶

get_metadata(
    file: Union[str, BytesIO, Path]
) -> Dict[str, Any]

Gets metadata for a file.

FileAttachment ¶

Bases: BaseAttachment

Represents a generic file attachment.

You should use VideoAttachment for videos, AudioAttachment for audio, and ImageAttachment for images. This is for everything else.

Parameters:

Name	Type	Description	Default
`file`	`Union[str, BytesIO, Path]`	The file to upload	required
`file_name`	`Optional[str]`	The name of the file	`None`
`mime_type`	`Optional[str]`	The mime type of the file	`None`
`size_bytes`	`Optional[int]`	The size of the file in bytes	`None`

get_metadata `async` `classmethod` ¶

get_metadata(
    file: Union[str, BytesIO, Path]
) -> Dict[str, Any]

Dud method, there's no metadata to fetch for a generic file.

ImageAttachment ¶

Bases: BaseAttachment

Represents an image attachment.

Parameters:

Name	Type	Description	Default
`file`	`Union[str, BytesIO, Path]`	The file to upload	required
`file_name`	`Optional[str]`	The name of the file	`None`
`mime_type`	`Optional[str]`	The mime type of the file	`None`
`size_bytes`	`Optional[int]`	The size of the file in bytes	`None`
`height`	`Optional[int]`	The height of the image in pixels (e.g. 1080)	`None`
`width`	`Optional[int]`	The width of the image in pixels (e.g. 1920)	`None`
`thumbnail`	`Optional[ImageAttachment]`	A thumbnail of the image. NOT a blurhash.	`None`
`xyz_amorgan_blurhash`	`Optional[str]`	The blurhash of the image	`None`

Attributes:

Name	Type	Description
`thumbnail`		A thumbnail of the image. NOT a blurhash.

from_file `async` `classmethod` ¶

from_file(
    file: Union[str, BytesIO, Path],
    file_name: Optional[str] = None,
    height: Optional[int] = None,
    width: Optional[int] = None,
    thumbnail: Union[
        ImageAttachment, Literal[False]
    ] = None,
    generate_blurhash: bool = True,
    *,
    xyz_amorgan_blurhash: Optional[str] = None
) -> ImageAttachment

Generates an image attachment

Parameters:

Name	Type	Description	Default
`file`	`Union[str, BytesIO, Path]`	The file to upload	required
`file_name`	`Optional[str]`	The name of the file (only used if file is a `BytesIO`)	`None`
`height`	`Optional[int]`	The height, in pixels, of this image	`None`
`width`	`Optional[int]`	The width, in pixels, of this image	`None`
`thumbnail`	`Union[ImageAttachment, Literal[False]]`	A thumbnail for this image	`None`
`generate_blurhash`	`bool`	Whether to generate a blurhash for this image	`True`
`xyz_amorgan_blurhash`	`Optional[str]`	The blurhash of the image, if known beforehand.	`None`

Returns:

Type	Description
`ImageAttachment`	An image attachment

generate_blur_hash `staticmethod` ¶

generate_blur_hash(
    file: Union[str, Path, BytesIO, Image],
    parts: Tuple[int, int] = (4, 3),
) -> str

Creates a blurhash

This function may be resource intensive

This function may be resource intensive, especially for large images. You should run this in a thread or process pool.

You should also scale any images down in order to increase performance.

See: woltapp/blurhash

get_blurhash `async` ¶

get_blurhash(
    quality: Tuple[int, int] = (4, 3),
    file: Optional[Union[str, Path, BytesIO, Image]] = None,
    disable_auto_crop: bool = False,
) -> str

Gets the blurhash of the attachment. See: woltapp/blurhash

Parameters:

Name	Type	Description	Default
`quality`	`Tuple[int, int]`	A tuple of the quality to generate the blurhash at. Defaults to (4, 3).	`(4, 3)`
`file`	`Optional[Union[str, Path, BytesIO, Image]]`	The file to generate the blurhash from. Defaults to the file passed in the constructor.	`None`
`disable_auto_crop`	`bool`	Whether to disable automatic cropping of the image. Defaults to False.	`False`

Returns:

Type	Description
`str`	The blurhash

generate_thumbnail `staticmethod` ¶

generate_thumbnail(
    image: Union[Image, BytesIO, str, Path],
    size: Tuple[int, int] = (320, 240),
    resampling: Union[Resampling] = BICUBIC,
) -> Image

Generates a small thumbnail of a large image.

Parameters:

Name	Type	Description	Default
`image`	`Union[Image, BytesIO, str, Path]`	The image to generate a thumbnail of. Can be a PIL Image, BytesIO, or a path.	required
`size`	`Tuple[int, int]`	The size of the thumbnail to generate in width x height. Defaults to (320, 240).	`(320, 240)`
`resampling`	`Union[Resampling]`	The resampling algorithm to use. Defaults to `PIL.Image.Resampling.BICUBIC`.	`BICUBIC`

Returns:

Type	Description
`Image`	The generated PIL image object

get_metadata `async` `classmethod` ¶

get_metadata(
    file: Union[str, BytesIO, Path]
) -> Dict[str, Any]

Gets metadata for an image.

New in v1.3.0

This function is new in v1.3.0. Additionally, unlike the previous way of fetching metadata, this function does NOT fall back to using imagemagick/ffmpeg. If you use a format too new, it may error.

set_thumbnail ¶

set_thumbnail(thumbnail: ImageAttachment) -> Self

Sets the thumbnail for this image attachment.

Parameters:

Name	Type	Description	Default
`thumbnail`	`ImageAttachment`	The thumbnail to set	required

VideoAttachment ¶

Bases: BaseAttachment

Represents a video attachment.

Parameters:

Name	Type	Description	Default
`file`	`Union[str, BytesIO, Path]`	The file to upload	required
`file_name`	`Optional[str]`	The name of the file	`None`
`mime_type`	`Optional[str]`	The mime type of the file	`None`
`size_bytes`	`Optional[int]`	The size of the file in bytes	`None`
`height`	`Optional[int]`	The height of the video in pixels (e.g. 1080)	`None`
`width`	`Optional[int]`	The width of the video in pixels (e.g. 1920)	`None`
`duration`	`Optional[int]`	The duration of the video in seconds	`None`
`thumbnail`	`Optional[ImageAttachment]`	A thumbnail of the video. NOT a blurhash.	`None`

generate_thumbnail `async` `staticmethod` ¶

generate_thumbnail(
    video: Union[str, Path, VideoAttachment]
) -> ImageAttachment

Generates a thumbnail for a video.

Parameters:

Name	Type	Description	Default
`video`	`Union[str, Path, VideoAttachment]`	The video to generate a thumbnail for	required

Returns:

Type	Description
`ImageAttachment`	The path to the generated thumbnail

get_metadata `async` `classmethod` ¶

get_metadata(file: Union[str, Path]) -> Dict[str, Any]

Get metadata about a video file.

Parameters:

Name	Type	Description	Default
`file`	`Union[str, Path]`	The video file to get metadata for	required

Returns:

Type	Description
`Dict[str, Any]`	The metadata

extract_first_frame `async` `staticmethod` ¶

extract_first_frame(
    file: Union[str, Path], file_format: str = "webp"
) -> bytes

Gets the first frame of a video.

Parameters:

Name	Type	Description	Default
`file`	`Union[str, Path]`	The video file to get the first frame of	required
`file_format`	`str`	The format to save the first frame in. Defaults to WebP, which is a good choice.	`'webp'`

Returns:

Type	Description
`bytes`	The first frame

from_file `async` `classmethod` ¶

from_file(
    file: Union[str, BytesIO, Path],
    file_name: Optional[str] = None,
    duration: Optional[int] = None,
    height: Optional[int] = None,
    width: Optional[int] = None,
    thumbnail: Optional[
        Union[ImageAttachment, Literal[False]]
    ] = None,
    generate_blurhash: bool = True,
) -> VideoAttachment

Generates a video attachment

This function auto-generates a thumbnail!

As thumbnails greatly improve user experience, even with blurhashes enabled, this function will by default create a thumbnail of the first frame of the given video if you do not provide one yourself. This may increase your initialisation time by a couple seconds, give or take!

If this is undesirable, pass thumbnail=False to disable generating a thumbnail. This is independent of generate_blurhash.

Generated thumbnails are always WebP images, so they will always be miniature, so you shouldn't notice a significant increase in upload time, especially considering your video will likely be several megabytes.

Parameters:

Name	Type	Description	Default
`file`	`Union[str, BytesIO, Path]`	The file to upload	required
`file_name`	`Optional[str]`	The name of the file (only used if file is a `BytesIO`)	`None`
`duration`	`Optional[int]`	The duration of the video, in seconds	`None`
`height`	`Optional[int]`	The height, in pixels, of this video	`None`
`width`	`Optional[int]`	The width, in pixels, of this video	`None`
`thumbnail`	`Optional[Union[ImageAttachment, Literal[False]]]`	A thumbnail for this image	`None`
`generate_blurhash`	`bool`	Whether to generate a blurhash for this image	`True`

Returns:

Type	Description
`VideoAttachment`	An image attachment

detect_mime_type ¶

detect_mime_type(file: Union[str, BytesIO, Path]) -> str

Detect the mime type of a file.

Parameters:

Name	Type	Description	Default
`file`	`Union[str, BytesIO, Path]`	The file to detect the mime type of. Can be a BytesIO.	required

Returns:

Type	Description
`str`	The mime type of the file (e.g. `text/plain`, `image/png`, `application/pdf`, `video/webp` etc.)

Raises:

Type	Description
`RuntimeError`	If the `magic` library is not installed.
`TypeError`	If the file is not a string, BytesIO, or Path object.

run_blocking `async` ¶

run_blocking(
    function: Callable[..., T], *args: Any, **kwargs: Any
) -> T

Takes a blocking function and runs it in a thread, returning the result.

You should use this for any long-running functions that may take a long time to respond that are not coroutines that you can await. For example, running a subprocess.

Example

import asyncio
import subprocess
from niobot.utils import run_blocking

async def main():
    result = await run_blocking(subprocess.run, ["find", "*.py", "-type", "f"], capture_output=True)
    print(result)

asyncio.run(main())

Parameters:

Name	Type	Description	Default
`function`	`Callable[..., T]`	The function to call. Make sure you do not call it, just pass it.	required
`args`	`Any`	The arguments to pass to the function.	`()`
`kwargs`	`Any`	The keyword arguments to pass to the function.	`{}`

Returns:

Type	Description
`T`	The result of the function.

which ¶

which(
    file_: Union[BytesIO, Path, str],
    mime_type: Optional[str] = None,
) -> Union[
    Type[FileAttachment],
    Type[ImageAttachment],
    Type[AudioAttachment],
    Type[VideoAttachment],
]

Gets the correct attachment type for a file.

This function will provide either Image/Video/Audio attachment where possible, or FileAttachment otherwise.

For example, image/png (from my_image.png) will see image/ and will return ImageAttachment, and video/mp4 (from my_video.mp4) will see video/ and will return VideoAttachment.

If the mime type cannot be mapped to an attachment type, this function will return FileAttachment.

Usage

import niobot
import pathlib

my_file = pathlib.Path("/tmp/foo.bar")
attachment = await niobot.which(my_file).from_file(my_file)
# or
attachment_type = niobot.which(my_file)  # one of the BaseAttachment subclasses
attachment = await attachment_type.from_file(my_file)

Parameters:

Name	Type	Description	Default
`file_`	`Union[BytesIO, Path, str]`	The file or BytesIO to investigate	required
`mime_type`	`Optional[str]`	The optional pre-detected mime type. If this is not provided, it will be detected.	`None`

Returns:

Type	Description
`Union[Type[FileAttachment], Type[ImageAttachment], Type[AudioAttachment], Type[VideoAttachment]]`	The correct type for this attachment (not instantiated)

Attachments¶

AudioAttachment ¶

duration property writable ¶

from_file async classmethod ¶

get_metadata async classmethod ¶

AttachmentType ¶

BaseAttachment ¶

size_bytes property ¶

as_body ¶

from_file async classmethod ¶

from_mxc async classmethod ¶

from_http async classmethod ¶

size_as ¶

upload async ¶

get_metadata abstractmethod async classmethod ¶

FileAttachment ¶

get_metadata async classmethod ¶

ImageAttachment ¶

from_file async classmethod ¶

generate_blur_hash staticmethod ¶

get_blurhash async ¶

generate_thumbnail staticmethod ¶

get_metadata async classmethod ¶

set_thumbnail ¶

VideoAttachment ¶

generate_thumbnail async staticmethod ¶

get_metadata async classmethod ¶

extract_first_frame async staticmethod ¶

from_file async classmethod ¶

detect_mime_type ¶

run_blocking async ¶

which ¶

duration `property` `writable` ¶

from_file `async` `classmethod` ¶

get_metadata `async` `classmethod` ¶

size_bytes `property` ¶

from_file `async` `classmethod` ¶

from_mxc `async` `classmethod` ¶

from_http `async` `classmethod` ¶

upload `async` ¶

get_metadata `abstractmethod` `async` `classmethod` ¶

get_metadata `async` `classmethod` ¶

from_file `async` `classmethod` ¶

generate_blur_hash `staticmethod` ¶

get_blurhash `async` ¶

generate_thumbnail `staticmethod` ¶

get_metadata `async` `classmethod` ¶

generate_thumbnail `async` `staticmethod` ¶

get_metadata `async` `classmethod` ¶

extract_first_frame `async` `staticmethod` ¶

from_file `async` `classmethod` ¶

run_blocking `async` ¶