PyDLNA 0.1.4__py3-none-any.whl

pydlna/__init__.py

@@ -0,0 +1,25 @@
+"""PyDLNA — a tiny DLNA/UPnP media server and control point library."""
+
+from pydlna.client import DLNAClient, DLNAController, PlaybackPosition, UPnPServiceInfo
+from pydlna.discovery import DLNADiscovery
+from pydlna.errors import UPnPError
+from pydlna.file import MediaFile, MediaItem
+from pydlna.server import DLNAServer, MediaLibrary
+
+try:
+    from pydlna._version import __version__
+except ImportError:
+    __version__ = "0.0.0.dev0"
+
+__all__ = [
+    "DLNAClient",
+    "DLNAController",
+    "DLNADiscovery",
+    "DLNAServer",
+    "MediaFile",
+    "MediaItem",
+    "MediaLibrary",
+    "PlaybackPosition",
+    "UPnPError",
+    "UPnPServiceInfo",
+]

pydlna/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.4'
+__version_tuple__ = version_tuple = (0, 1, 4)
+
+__commit_id__ = commit_id = None

pydlna/client.py

@@ -0,0 +1,290 @@
+"""DLNA clients (discovered devices) and the control point that drives them."""
+
+from __future__ import annotations
+
+import logging
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Mapping, Optional, Union
+from urllib.parse import urljoin
+from xml.etree import ElementTree as ET
+
+from pydlna.errors import UPnPError
+from pydlna.file import MediaFile, MediaItem
+from pydlna.formatters import XMLFormatter
+
+logger = logging.getLogger(__name__)
+
+_DEVICE_NS = {"upnp": "urn:schemas-upnp-org:device-1-0"}
+
+
+@dataclass
+class UPnPServiceInfo:
+    """One service entry from a device's description document."""
+
+    service_type: str
+    service_id: str = ""
+    control_url: str = ""
+    scpd_url: str = ""
+    event_url: str = ""
+
+
+@dataclass
+class PlaybackPosition:
+    """A snapshot of what a renderer is playing right now."""
+
+    position: str = ""
+    duration: str = ""
+    title: str = ""
+    uri: str = ""
+
+
+@dataclass
+class DLNAClient:
+    """A DLNA/UPnP device discovered on the network."""
+
+    name: str = ""
+    address: Optional[str] = None
+    location: Optional[str] = None
+    udn: str = ""
+    server: str = ""
+    st: str = ""
+    usn: str = ""
+    device_type: str = ""
+    manufacturer: str = ""
+    manufacturer_url: str = ""
+    model_name: str = ""
+    model_number: str = ""
+    model_description: str = ""
+    serial_number: str = ""
+    icons: list[str] = field(default_factory=list)
+    services: dict[str, str] = field(default_factory=dict)
+    service_details: list[UPnPServiceInfo] = field(default_factory=list)
+    _protocol_cache: Optional[dict] = field(default=None, repr=False)
+
+    @classmethod
+    def from_ssdp(cls, address: str, headers: Mapping[str, str]) -> "DLNAClient":
+        """Build a client from the sender address and headers of an SSDP message."""
+        return cls(
+            address=address,
+            location=headers.get("location"),
+            server=headers.get("server", ""),
+            st=headers.get("st", ""),
+            usn=headers.get("usn", ""),
+        )
+
+    @property
+    def is_renderer(self) -> bool:
+        return "MediaRenderer" in (self.device_type or self.st)
+
+    @property
+    def is_server(self) -> bool:
+        return "MediaServer" in (self.device_type or self.st)
+
+    @property
+    def supported_protocols(self) -> list[str]:
+        """Raw ``protocolInfo`` entries the renderer accepts (its Sink list)."""
+        sink = self._protocols().get("Sink", "")
+        return [entry for entry in sink.split(",") if entry.strip()]
+
+    @property
+    def playback_formats(self) -> list[str]:
+        """MIME types the renderer can play, parsed from its Sink list."""
+        return [p.split(":")[2] for p in self.supported_protocols if p.count(":") >= 2]
+
+    def _protocols(self) -> dict[str, str]:
+        """Cached ConnectionManager ``GetProtocolInfo`` call (best effort)."""
+        if self._protocol_cache is None:
+            try:
+                self._protocol_cache = self.controller().get_protocol_info()
+            except (UPnPError, OSError):
+                self._protocol_cache = {}
+        return self._protocol_cache
+
+    def fetch_description(self, timeout: float = 5.0) -> bool:
+        """Fetch and parse the device description document (best effort)."""
+        if not self.location:
+            return False
+        try:
+            with urllib.request.urlopen(self.location, timeout=timeout) as response:
+                root = ET.fromstring(response.read())
+        except (OSError, ET.ParseError) as exc:
+            logger.debug("Could not fetch %s: %s", self.location, exc)
+            return False
+        device = root.find("upnp:device", _DEVICE_NS)
+        if device is None:
+            return False
+        self.name = device.findtext("upnp:friendlyName", "", _DEVICE_NS)
+        self.udn = device.findtext("upnp:UDN", "", _DEVICE_NS)
+        self.device_type = device.findtext("upnp:deviceType", "", _DEVICE_NS)
+        self.manufacturer = device.findtext("upnp:manufacturer", "", _DEVICE_NS)
+        self.manufacturer_url = device.findtext("upnp:manufacturerURL", "", _DEVICE_NS)
+        self.model_name = device.findtext("upnp:modelName", "", _DEVICE_NS)
+        self.model_number = device.findtext("upnp:modelNumber", "", _DEVICE_NS)
+        self.model_description = device.findtext("upnp:modelDescription", "", _DEVICE_NS)
+        self.serial_number = device.findtext("upnp:serialNumber", "", _DEVICE_NS)
+        self.icons.clear()
+        self.services.clear()
+        self.service_details.clear()
+        for icon in device.findall("upnp:iconList/upnp:icon", _DEVICE_NS):
+            url = icon.findtext("upnp:url", "", _DEVICE_NS)
+            if url:
+                self.icons.append(urljoin(self.location, url))
+        for service in device.findall("upnp:serviceList/upnp:service", _DEVICE_NS):
+            detail = UPnPServiceInfo(
+                service_type=service.findtext("upnp:serviceType", "", _DEVICE_NS),
+                service_id=service.findtext("upnp:serviceId", "", _DEVICE_NS),
+                control_url=self._absolute(service.findtext("upnp:controlURL", "", _DEVICE_NS)),
+                scpd_url=self._absolute(service.findtext("upnp:SCPDURL", "", _DEVICE_NS)),
+                event_url=self._absolute(service.findtext("upnp:eventSubURL", "", _DEVICE_NS)),
+            )
+            self.service_details.append(detail)
+            if detail.service_type and detail.control_url:
+                self.services[detail.service_type] = detail.control_url
+        return True
+
+    def _absolute(self, url: str) -> str:
+        """Resolve a possibly-relative URL against the description location."""
+        return urljoin(self.location, url) if url else ""
+
+    def controller(self) -> "DLNAController":
+        return DLNAController(self)
+
+
+class DLNAController:
+    """A UPnP control point: calls SOAP actions on a ``DLNAClient``."""
+
+    def __init__(self, client: Optional[DLNAClient] = None) -> None:
+        self.client = client or DLNAClient()
+
+    def __enter__(self) -> "DLNAController":
+        """The controller doubles as a ``with`` session for readability."""
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        pass
+
+    # -- Generic action call -----------------------------------------------
+
+    def _request(self, service: str, action: str, **args: object) -> dict[str, str]:
+        service_type = f"urn:schemas-upnp-org:service:{service}:1"
+        url = self.client.services.get(service_type)
+        if url is None and self.client.fetch_description():
+            url = self.client.services.get(service_type)
+        if url is None:
+            raise UPnPError(401, f"Device does not expose {service}")
+        envelope = XMLFormatter.soap_envelope(action, service_type, args)
+        request = urllib.request.Request(
+            url,
+            data=envelope.encode("utf-8"),
+            headers={
+                "Content-Type": 'text/xml; charset="utf-8"',
+                "SOAPAction": f'"{service_type}#{action}"',
+                "User-Agent": "PyDLNA/0.1 UPnP/1.1",
+            },
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=10) as response:
+                return XMLFormatter.parse_soap_response(response.read(), action)
+        except urllib.error.HTTPError as exc:
+            # UPnP devices answer failures with HTTP 500 + a SOAP fault body.
+            return XMLFormatter.parse_soap_response(exc.read(), action)
+
+    # -- ContentDirectory ----------------------------------------------------
+
+    def browse(self, object_id: str = "0", browse_flag: str = "BrowseDirectChildren",
+               filter: str = "*", start: int = 0, count: int = 0,
+               sort: str = "") -> dict[str, str]:
+        """Browse a media server; returns the raw response fields."""
+        return self._request(
+            "ContentDirectory", "Browse",
+            ObjectID=object_id, BrowseFlag=browse_flag, Filter=filter,
+            StartingIndex=str(start), RequestedCount=str(count), SortCriteria=sort,
+        )
+
+    def browse_items(self, object_id: str = "0", **kwargs: object) -> list[MediaItem]:
+        """Browse a media server and parse the DIDL-Lite result."""
+        response = self.browse(object_id, **kwargs)
+        return XMLFormatter.parse_didl_lite(response.get("Result", ""))
+
+    # -- AVTransport (renderers) ----------------------------------------------
+
+    def set_av_transport_uri(self, uri: str, metadata: str = "") -> dict[str, str]:
+        return self._request("AVTransport", "SetAVTransportURI",
+                             InstanceID="0", CurrentURI=uri, CurrentURIMetaData=metadata)
+
+    def play(self, media: Optional[Union[MediaFile, str]] = None,
+             speed: str = "1") -> dict[str, str]:
+        """Start playback, optionally loading a ``MediaFile`` or URL first."""
+        if isinstance(media, MediaFile):
+            url = media.url_for(self.client.address)
+            if not url:
+                raise ValueError("MediaFile is not attached to a server library")
+            base_url = url.rsplit("/media/", 1)[0]
+            self.set_av_transport_uri(url, XMLFormatter.didl_items([media], base_url))
+        elif isinstance(media, str):
+            self.set_av_transport_uri(media)
+        return self._request("AVTransport", "Play", InstanceID="0", Speed=speed)
+
+    def is_playing(self) -> bool:
+        """True while the renderer reports ``PLAYING`` (best effort)."""
+        try:
+            return self.get_transport_info().get("CurrentTransportState") == "PLAYING"
+        except (UPnPError, OSError):
+            return False
+
+    @property
+    def currently_playing(self) -> PlaybackPosition:
+        """Position, duration and title of the current track (best effort)."""
+        try:
+            info = self.get_position_info()
+        except (UPnPError, OSError):
+            return PlaybackPosition()
+        title = ""
+        metadata = info.get("TrackMetaData", "")
+        if metadata:
+            tracks = XMLFormatter.parse_didl_lite(metadata)
+            if tracks:
+                title = tracks[0].title
+        return PlaybackPosition(
+            position=info.get("RelTime", ""),
+            duration=info.get("TrackDuration", ""),
+            title=title,
+            uri=info.get("TrackURI", ""),
+        )
+
+    def pause(self) -> dict[str, str]:
+        return self._request("AVTransport", "Pause", InstanceID="0")
+
+    def stop(self) -> dict[str, str]:
+        return self._request("AVTransport", "Stop", InstanceID="0")
+
+    # -- RenderingControl --------------------------------------------------------
+
+    def get_volume(self, channel: str = "Master") -> int:
+        response = self._request("RenderingControl", "GetVolume",
+                                 InstanceID="0", Channel=channel)
+        return int(response.get("CurrentVolume") or 0)
+
+    def set_volume(self, volume: int, channel: str = "Master") -> dict[str, str]:
+        return self._request("RenderingControl", "SetVolume",
+                             InstanceID="0", Channel=channel, DesiredVolume=str(volume))
+
+    # -- Status queries ---------------------------------------------------------
+
+    def get_transport_info(self) -> dict[str, str]:
+        """Playback state: CurrentTransportState, CurrentTransportStatus, Speed."""
+        return self._request("AVTransport", "GetTransportInfo", InstanceID="0")
+
+    def get_media_info(self) -> dict[str, str]:
+        """The renderer's currently loaded media (CurrentURI, duration, ...)."""
+        return self._request("AVTransport", "GetMediaInfo", InstanceID="0")
+
+    def get_position_info(self) -> dict[str, str]:
+        """Position within the current track (RelTime, TrackDuration, ...)."""
+        return self._request("AVTransport", "GetPositionInfo", InstanceID="0")
+
+    def get_protocol_info(self) -> dict[str, str]:
+        """Source/Sink protocol lists; a renderer's Sink is its format support."""
+        return self._request("ConnectionManager", "GetProtocolInfo")

pydlna/discovery.py

@@ -0,0 +1,195 @@
+"""SSDP discovery: find DLNA devices on the LAN, and advertise our server."""
+
+from __future__ import annotations
+
+import logging
+import socket
+import threading
+import time
+
+from pydlna.client import DLNAClient
+
+logger = logging.getLogger(__name__)
+
+SSDP_ADDR = "239.255.255.250"
+SSDP_PORT = 1900
+
+MEDIA_SERVER = "urn:schemas-upnp-org:device:MediaServer:1"
+MEDIA_RENDERER = "urn:schemas-upnp-org:device:MediaRenderer:1"
+
+_SERVER_HEADER = "PyDLNA/0.1 UPnP/1.0 DLNADOC/1.50"
+
+
+class DeviceList(list):
+    """The result of a discovery run; usable as a context manager.
+
+    ``with DLNADiscovery().discover() as devices:`` works purely for
+    symmetry with the server/controller — there is nothing to close.
+    """
+
+    def __enter__(self) -> "DeviceList":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        pass
+
+
+class DLNADiscovery:
+    """Finds DLNA/UPnP devices on the local network via SSDP M-SEARCH."""
+
+    def __init__(self, st: str = "ssdp:all") -> None:
+        self.st = st
+        self.clients: list[DLNAClient] = []
+
+    def discover(self, timeout: float = 3.0, resolve_names: bool = True) -> list[DLNAClient]:
+        """Send an M-SEARCH multicast and collect the devices that answer."""
+        request = _msearch(self.st, mx=max(1, min(int(timeout), 5)))
+        found: dict[str, DLNAClient] = {}
+        sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP)
+        try:
+            sock.setsockopt(socket.IPPROTO_IP, socket.IP_MULTICAST_TTL, 2)
+            sock.settimeout(0.2)
+            sock.sendto(request.encode("ascii"), (SSDP_ADDR, SSDP_PORT))
+            deadline = time.monotonic() + timeout
+            while time.monotonic() < deadline:
+                try:
+                    data, address = sock.recvfrom(4096)
+                except socket.timeout:
+                    continue
+                headers = _parse_headers(data.decode("latin-1"))
+                usn = headers.get("usn") or headers.get("location", "")
+                # A device announces once per ST as "udn::nt"; dedupe on the UDN.
+                key = usn.split("::")[0]
+                if not key or key in found:
+                    continue
+                found[key] = DLNAClient.from_ssdp(address[0], headers)
+        finally:
+            sock.close()
+        self.clients = DeviceList(found.values())
+        if resolve_names:
+            for client in self.clients:
+                client.fetch_description(timeout=1.5)  # best effort
+        return self.clients
+
+
+class SSDPResponder(threading.Thread):
+    """Answers M-SEARCH requests and multicasts alive/byebye notifications."""
+
+    def __init__(self, udn: str, location: str, interval: float = 60.0) -> None:
+        super().__init__(name="pydlna-ssdp", daemon=True)
+        self.udn = udn
+        self.location = location
+        self.interval = interval
+        self._stop_event = threading.Event()
+
+    @property
+    def targets(self) -> list[tuple[str, str]]:
+        """Every ``(NT, USN)`` pair this device advertises."""
+        content_directory = "urn:schemas-upnp-org:service:ContentDirectory:1"
+        connection_manager = "urn:schemas-upnp-org:service:ConnectionManager:1"
+        return [
+            ("upnp:rootdevice", f"{self.udn}::upnp:rootdevice"),
+            (self.udn, self.udn),
+            (MEDIA_SERVER, f"{self.udn}::{MEDIA_SERVER}"),
+            (content_directory, f"{self.udn}::{content_directory}"),
+            (connection_manager, f"{self.udn}::{connection_manager}"),
+        ]
+
+    def stop(self) -> None:
+        self._stop_event.set()
+
+    def run(self) -> None:
+        sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP)
+        try:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            sock.bind(("", SSDP_PORT))
+            membership = socket.inet_aton(SSDP_ADDR) + socket.inet_aton("0.0.0.0")
+            sock.setsockopt(socket.IPPROTO_IP, socket.IP_ADD_MEMBERSHIP, membership)
+            sock.settimeout(1.0)
+        except OSError as exc:
+            logger.warning("SSDP responder disabled: %s", exc)
+            sock.close()
+            return
+        try:
+            self._announce(sock, "ssdp:alive")
+            next_announce = time.monotonic() + self.interval
+            while not self._stop_event.is_set():
+                try:
+                    data, address = sock.recvfrom(2048)
+                except socket.timeout:
+                    pass
+                except OSError:
+                    break
+                else:
+                    self._maybe_respond(sock, data, address)
+                if time.monotonic() >= next_announce:
+                    self._announce(sock, "ssdp:alive")
+                    next_announce = time.monotonic() + self.interval
+        finally:
+            try:
+                self._announce(sock, "ssdp:byebye")
+            except OSError:
+                pass
+            sock.close()
+
+    def _maybe_respond(self, sock: socket.socket, data: bytes, address: tuple) -> None:
+        message = data.decode("latin-1", errors="replace")
+        if not message.startswith("M-SEARCH"):
+            return
+        st = _parse_headers(message).get("st", "")
+        if st == "ssdp:all":
+            matches = self.targets
+        else:
+            matches = [(nt, usn) for nt, usn in self.targets if nt == st]
+        for nt, usn in matches:
+            response = (
+                "HTTP/1.1 200 OK\r\n"
+                "CACHE-CONTROL: max-age=1800\r\n"
+                "EXT:\r\n"
+                f"LOCATION: {self.location}\r\n"
+                f"SERVER: {_SERVER_HEADER}\r\n"
+                f"ST: {nt}\r\n"
+                f"USN: {usn}\r\n\r\n"
+            )
+            try:
+                sock.sendto(response.encode("ascii"), address)
+            except OSError:
+                pass
+
+    def _announce(self, sock: socket.socket, nts: str) -> None:
+        for nt, usn in self.targets:
+            message = (
+                "NOTIFY * HTTP/1.1\r\n"
+                f"HOST: {SSDP_ADDR}:{SSDP_PORT}\r\n"
+                "CACHE-CONTROL: max-age=1800\r\n"
+                f"LOCATION: {self.location}\r\n"
+                f"NT: {nt}\r\n"
+                f"NTS: {nts}\r\n"
+                f"SERVER: {_SERVER_HEADER}\r\n"
+                f"USN: {usn}\r\n\r\n"
+            )
+            try:
+                sock.sendto(message.encode("ascii"), (SSDP_ADDR, SSDP_PORT))
+            except OSError:
+                pass
+
+
+def _msearch(st: str, mx: int) -> str:
+    return (
+        "M-SEARCH * HTTP/1.1\r\n"
+        f"HOST: {SSDP_ADDR}:{SSDP_PORT}\r\n"
+        'MAN: "ssdp:discover"\r\n'
+        f"MX: {mx}\r\n"
+        f"ST: {st}\r\n"
+        f"USER-AGENT: {_SERVER_HEADER}\r\n\r\n"
+    )
+
+
+def _parse_headers(message: str) -> dict[str, str]:
+    """Parse the header block of an SSDP message into a lowercase-keyed dict."""
+    headers = {}
+    for line in message.split("\r\n")[1:]:
+        key, separator, value = line.partition(":")
+        if separator:
+            headers[key.strip().lower()] = value.strip()
+    return headers

pydlna/errors.py

@@ -0,0 +1,15 @@
+"""Exceptions raised by PyDLNA."""
+
+
+class UPnPError(Exception):
+    """A UPnP-level error.
+
+    Raised by the server to abort a SOAP action (the HTTP layer turns it
+    into a SOAP fault) and by the client when a remote device answers an
+    action call with a fault.
+    """
+
+    def __init__(self, code: int, description: str = "") -> None:
+        super().__init__(f"UPnP error {code}: {description or 'unknown'}")
+        self.code = code
+        self.description = description

pydlna/file.py

@@ -0,0 +1,101 @@
+"""Media models shared by the PyDLNA server and client."""
+
+from __future__ import annotations
+
+import mimetypes
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from pydlna.server import MediaLibrary
+
+# Best-effort DLNA profile names keyed by MIME type. Anything not listed is
+# advertised with a wildcard profile, which most renderers still accept.
+_DLNA_PROFILES = {
+    "audio/mpeg": "MP3",
+    "audio/mp4": "AAC_ISO",
+    "audio/x-m4a": "AAC_ISO",
+    "audio/wav": "LPCM",
+    "audio/x-wav": "LPCM",
+    "image/jpeg": "JPEG_LRG",
+    "image/png": "PNG_LRG",
+    "video/mp4": "AVC_MP4_MP_HD_720p_AAC",
+    "video/mpeg": "MPEG_PS_PAL",
+}
+
+
+@dataclass
+class MediaFile:
+    """A local file exposed by the media server."""
+
+    path: Path
+    title: Optional[str] = None
+    mime_type: Optional[str] = None
+    id: str = ""
+    library: Optional["MediaLibrary"] = field(default=None, repr=False)
+
+    def __post_init__(self) -> None:
+        self.path = Path(self.path)
+        if self.title is None:
+            self.title = self.path.stem
+        if self.mime_type is None:
+            self.mime_type = mimetypes.guess_type(self.path.name)[0] or "application/octet-stream"
+
+    @property
+    def size(self) -> int:
+        try:
+            return self.path.stat().st_size
+        except OSError:
+            return 0
+
+    @property
+    def dlna_profile(self) -> str:
+        return _DLNA_PROFILES.get(self.mime_type or "", "*")
+
+    @property
+    def upnp_class(self) -> str:
+        top = (self.mime_type or "").split("/", 1)[0]
+        return {
+            "audio": "object.item.audioItem.musicTrack",
+            "video": "object.item.videoItem",
+            "image": "object.item.imageItem.photo",
+        }.get(top, "object.item")
+
+    @property
+    def protocol_info(self) -> str:
+        """The ``protocolInfo`` attribute used in DIDL-Lite ``<res>`` elements."""
+        profile = f"DLNA.ORG_PN={self.dlna_profile};" if self.dlna_profile != "*" else ""
+        return f"http-get:*:{self.mime_type}:{profile}DLNA.ORG_OP=01;DLNA.ORG_CI=0"
+
+    @property
+    def url(self) -> str:
+        """Stream URL of this file, once it lives in a server's library."""
+        return self.url_for()
+
+    def url_for(self, target: Optional[str] = None) -> str:
+        """Stream URL whose local IP is chosen to be reachable from ``target``.
+
+        On multi-homed machines (VPN, Hyper-V/WSL adapters) the default LAN
+        IP guess can pick the wrong interface; passing the renderer's address
+        picks the local IP that would actually route to it.
+        """
+        server = self.library.server if self.library else None
+        if server is None or not self.id:
+            return ""
+        host = server.local_ip_for(target) if target else server.local_ip
+        return f"http://{host}:{server.port}/media/{self.id}"
+
+
+@dataclass
+class MediaItem:
+    """A media entry parsed from a DIDL-Lite document (client side)."""
+
+    id: str
+    parent_id: str = "0"
+    title: str = ""
+    upnp_class: str = ""
+    is_container: bool = False
+    url: str = ""
+    mime_type: str = ""
+    size: int = 0