rootpy-client 1.31.1__py3-none-any.whl

rootpy/__init__.py

@@ -0,0 +1,393 @@
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("rootpy-client")
+except PackageNotFoundError:  # running from a source tree, not installed
+    __version__ = "0.0.0.dev0"
+
+from .client import RootClient
+from .commands import (
+    Command,
+    CommandArgumentError,
+    CommandCheckFailure,
+    CommandError,
+    CommandNotFound,
+    Context,
+    parse_channel_id,
+    parse_channel_mention,
+    parse_user_id,
+    parse_user_mention,
+)
+from .emoji import normalize_reaction, parse_emoji_mention
+from .events import (
+    MessageAction,
+    ChannelAction,
+    CommunityLeaveReason,
+    CallDetachedEvent,
+    ChannelDeletedEvent,
+    ChannelEvent,
+    CommandErrorEvent,
+    CommandEvent,
+    CommunityDeletedEvent,
+    CommunityEvent,
+    CommunityLeaveEvent,
+    MessageEvent,
+    NotificationEvent,
+    ReadyEvent,
+)
+from .exceptions import (
+    ErrorInfo,
+    get_error_info,
+    format_root_error,
+    UsernameLookupAuthenticationRequired,
+    GrpcStatus,
+    GrpcCancelled,
+    GrpcUnknown,
+    GrpcInvalidArgument,
+    GrpcDeadlineExceeded,
+    GrpcNotFound,
+    GrpcAlreadyExists,
+    GrpcPermissionDenied,
+    GrpcResourceExhausted,
+    GrpcFailedPrecondition,
+    GrpcAborted,
+    GrpcOutOfRange,
+    GrpcUnimplemented,
+    GrpcInternal,
+    GrpcUnavailable,
+    GrpcDataLoss,
+    GrpcUnauthenticated,
+    AccountAlreadyExists,
+    AuthenticationError,
+    EmailAlreadyExists,
+    GrpcWebError,
+    RootError,
+    SignUpError,
+    TurnstileRequired,
+    UsernameAlreadyExists,
+)
+from .identifiers import (
+    normalize_root_guid,
+    root_guid_datetime,
+    root_guid_type,
+)
+from .media import (
+    MediaBackendInfo,
+    media_backend_info,
+)
+from .media_bootstrap import (
+    ensure_ffmpeg,
+    ensure_media_dependencies,
+)
+from .models import (
+    AuthenticationSession,
+    CallSession,
+    Channel,
+    ChannelGroup,
+    Community,
+    CommunityExtended,
+    CurrentUser,
+    Message,
+    MessageAttachment,
+    MessageSendResult,
+)
+from .packets import (
+    PacketType,
+    SocketPacket,
+)
+from .permissions import (
+    PermissionName,
+    AccessRule,
+    ChannelOverlay,
+    ChannelPermission,
+    CommunityPermission,
+    ActionNotApplicable,
+    CallActionError,
+    ChannelPermissions,
+    MissingPermissions,
+    PermissionStateUnavailable,
+)
+from .services.assets import AssetService
+from .services.direct_messages import (
+    DirectMessage,
+    DirectMessageService,
+)
+from .dm_member import DMMemberService
+from .users import User
+
+
+__all__ = [
+    "__version__",
+
+    # Client
+    "RootClient",
+    "ErrorInfo",
+    "get_error_info",
+
+    # Multi-account hosting
+    "MultiClientHost",
+    "HostedAccount",
+    "Outcome",
+    "format_root_error",
+
+    # Reading unread
+    "UnreadReader",
+    "UnreadChannel",
+    "is_unread",
+
+    # Presence and attach lifetime
+    "AttachHold",
+    "PresenceWatch",
+    "effective_presence",
+
+    # Commands
+    "Command",
+    "CommandArgumentError",
+    "CommandCheckFailure",
+    "CommandError",
+    "CommandNotFound",
+    "Context",
+    "parse_channel_id",
+    "parse_channel_mention",
+    "parse_user_id",
+    "parse_user_mention",
+
+    "normalize_reaction",
+    "parse_emoji_mention",
+
+    # Events
+    "CallDetachedEvent",
+    "ChannelDeletedEvent",
+    "ChannelEvent",
+    "CommandErrorEvent",
+    "CommandEvent",
+    "CommunityDeletedEvent",
+    "CommunityEvent",
+    "CommunityLeaveEvent",
+    "MessageEvent",
+    "NotificationEvent",
+    "ReadyEvent",
+
+    # Exceptions
+    "RootError",
+    "AuthenticationError",
+    "GrpcWebError",
+    "TurnstileRequired",
+    "SignUpError",
+    "AccountAlreadyExists",
+    "UsernameAlreadyExists",
+    "EmailAlreadyExists",
+
+    "normalize_root_guid",
+    "root_guid_datetime",
+    "root_guid_type",
+
+    # Models
+    "AuthenticationSession",
+    "CallSession",
+    "Channel",
+    "ChannelGroup",
+    "Community",
+    "CommunityExtended",
+    "CurrentUser",
+    "Message",
+    "MessageAttachment",
+    "MessageSendResult",
+    "User",
+
+    # Packets
+    "PacketType",
+    "SocketPacket",
+
+    # Permissions
+    "ActionNotApplicable",
+    # The base the other three share. Exported so `except CallActionError`
+    # catches a refused mute/kick in one clause -- the subclasses were
+    # reachable before, their base was not.
+    "CallActionError",
+    "ChannelPermissions",
+    "MissingPermissions",
+    "PermissionStateUnavailable",
+
+    # Direct messages
+    "DirectMessage",
+    "DirectMessageService",
+    "DMMemberService",
+    "DirectMessageError",
+
+    "AssetService",
+
+    # Voice / media
+    "AudioPlayback",
+    "IceInfo",
+    "MediaBackendInfo",
+    "media_backend_info",
+    "ensure_ffmpeg",
+    "ensure_media_dependencies",
+    "RawAPI",
+    "RawService",
+    "RawMethod",
+    "RawRpcResult",
+    "AccessRule",
+    "ChannelOverlay",
+    "ChannelPermission",
+    "CommunityPermission",
+    "CommunityAdminService",
+    "GrpcStatus",
+    "GrpcCancelled",
+    "GrpcUnknown",
+    "GrpcInvalidArgument",
+    "GrpcDeadlineExceeded",
+    "GrpcNotFound",
+    "GrpcAlreadyExists",
+    "GrpcPermissionDenied",
+    "GrpcResourceExhausted",
+    "GrpcFailedPrecondition",
+    "GrpcAborted",
+    "GrpcOutOfRange",
+    "GrpcUnimplemented",
+    "GrpcInternal",
+    "GrpcUnavailable",
+    "GrpcDataLoss",
+    "GrpcUnauthenticated",
+    "MessageAction",
+    "ChannelAction",
+    "CommunityLeaveReason",
+    "PermissionName",
+    "AttrDict",
+    "EnumValue",
+    "StructuredAPI",
+    "StructuredMethod",
+    "StructuredResult",
+    "StructuredService",
+    "UsernameLookupAuthenticationRequired",
+    "RootServiceFacade",
+    "RoleManager",
+    "MemberManager",
+    "CommunityFileManager",
+    "LogManager",
+    "CommunityAppManager",
+    "VoiceAdminManager",
+    "FriendshipGroupManager",
+]
+
+
+from .services.community_admin import CommunityAdminService
+
+
+from .service_facade import RootServiceFacade
+from .domain_managers import (
+    RoleManager,
+    MemberManager,
+    CommunityFileManager,
+    LogManager,
+    CommunityAppManager,
+    VoiceAdminManager,
+    FriendshipGroupManager,
+)
+
+from .object_api import CommunityManager, PermissionManager
+
+from .pagination import AsyncPager, Page
+
+from .events import EventErrorEvent
+
+from .exceptions import HttpStatusError, BadRequest, Unauthorized, Forbidden, HttpNotFound, Conflict, PayloadTooLarge, RateLimited, ServerError, BadGateway, ServiceUnavailable, GatewayTimeout, RetryExhausted, DirectMessageError
+
+from .root_exception import (
+    RootExceptionInfo,
+    ValidationError,
+    decode_root_exception,
+    decode_root_exception_header,
+)
+
+from .enums import (
+    ErrorCodeType,
+    PacketErrorCode,
+    ContentFlagReason,
+    NotificationType,
+    MessageType,
+    ChannelType,
+    UserOnlineStatus,
+)
+
+from .packet_schemas import PACKET_SCHEMAS, decode_packet
+
+from .events import ChannelActivity
+
+from .typed_events import (
+    BlockEvent,
+    ChannelEvent as TypedChannelEvent,
+    CommunityEvent as TypedCommunityEvent,
+    FriendEvent,
+    MemberEvent,
+    MemberRoleEvent,
+    ReactionEvent,
+    RoleEvent,
+)
+
+from .cache import LRUCache, StateCache
+
+from .validation import (
+    DEFAULT_PICTURE_HEX,
+    USERNAME_MAX_LENGTH,
+    USERNAME_MIN_LENGTH,
+    USERNAME_RULE,
+    normalize_hex_colour,
+    validate_nickname,
+    validate_username,
+)
+
+# The generated RPC registries are big and slow to import (~770 ms cold, about
+# half of total import time), and most programs never touch them. They load on
+# first use instead -- `from rootpy import StructuredAPI` still works, it just
+# pays the cost at that moment rather than on every import of the package.
+_LAZY_EXPORTS = {
+    "RawAPI": "raw_api",
+    "RawMethod": "raw_api",
+    "RawRpcResult": "raw_api",
+    "RawService": "raw_api",
+    "AttrDict": "structured_api",
+    "EnumValue": "structured_api",
+    "StructuredAPI": "structured_api",
+    "StructuredMethod": "structured_api",
+    "StructuredResult": "structured_api",
+    "StructuredService": "structured_api",
+    # Voice: rootpy.services.calls pulls in the media support modules, so it
+    # is kept off the import path too.
+    "AudioPlayback": "services.calls",
+    "IceInfo": "services.calls",
+}
+
+
+def __getattr__(name):
+    module_name = _LAZY_EXPORTS.get(name)
+    if module_name is None:
+        raise AttributeError(f"module 'rootpy' has no attribute {name!r}")
+    import importlib
+
+    module = importlib.import_module(f".{module_name}", __name__)
+    value = getattr(module, name)
+    globals()[name] = value        # cache it, so this happens once
+    return value
+
+from .host import HostedAccount, MultiClientHost, Outcome
+
+from .models import DetailedMember, UserProfile
+
+from .stats import EndpointStats, TransportStats
+
+from .unread import UnreadChannel, UnreadReader, is_unread
+
+from .attach import AttachHold
+
+from .presence import PresenceWatch, effective_presence
+
+from .services.assets import Asset, AssetLink
+
+from .accounts import (
+    AccountFactory,
+    AlreadyCreatedError,
+    CreatedAccount,
+    TurnstileChallenge,
+)

rootpy/_registry_loader.py

@@ -0,0 +1,122 @@
+"""Lazy loading for the generated protocol registries.
+
+The registries are large -- 842 message definitions, 842 raw schemas (the same
+key set, one field table per message), 31 services -- and most programs touch
+only a handful of them. Storing them as
+Python literals meant every field of every message was parsed and built into
+dicts before the first request could be sent.
+
+They now live as JSON under ``rootpy/data/``. :class:`LazyRegistry` is a
+read-only mapping that behaves exactly like the dict it replaced but defers
+reading and decoding the file until something actually looks a key up. Import
+stays cheap; the cost is paid once, on first use, by whoever needs it.
+
+``DerivedRegistry`` is the same idea for indexes that can be computed from
+another registry rather than stored (see ``SIMPLE_MESSAGES``).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Callable, Dict, Iterator, Mapping
+
+_DATA_DIR = Path(__file__).resolve().parent / "data"
+
+
+class LazyRegistry(Mapping):
+    """A read-only mapping backed by a JSON file, loaded on first access.
+
+    Implements the full :class:`~collections.abc.Mapping` protocol, so it is a
+    drop-in for the plain dicts these registries used to be: subscripting,
+    ``in``, ``.get()``, ``.items()``, ``len()`` and iteration all work.
+    """
+
+    __slots__ = ("_filename", "_data")
+
+    def __init__(self, filename: str) -> None:
+        self._filename = filename
+        self._data: Dict[str, Any] | None = None
+
+    def _load(self) -> Dict[str, Any]:
+        data = self._data
+        if data is None:
+            path = _DATA_DIR / self._filename
+            try:
+                with path.open("r", encoding="utf-8") as handle:
+                    data = json.load(handle)
+            except FileNotFoundError as exc:  # pragma: no cover - packaging bug
+                raise RuntimeError(
+                    f"rootpy data file {self._filename!r} is missing. The "
+                    "package was probably installed without its data files; "
+                    "reinstall rootpy."
+                ) from exc
+            self._data = data
+        return data
+
+    # -- Mapping protocol ------------------------------------------------
+    def __getitem__(self, key: str) -> Any:
+        return self._load()[key]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._load())
+
+    def __len__(self) -> int:
+        return len(self._load())
+
+    def __contains__(self, key: object) -> bool:
+        return key in self._load()
+
+    def __repr__(self) -> str:
+        state = "unloaded" if self._data is None else f"{len(self._data)} entries"
+        return f"<LazyRegistry {self._filename} ({state})>"
+
+    # -- conveniences ----------------------------------------------------
+    @property
+    def loaded(self) -> bool:
+        """True once the backing file has been read."""
+        return self._data is not None
+
+    def preload(self) -> "LazyRegistry":
+        """Force the load now, e.g. to keep it off a latency-sensitive path."""
+        self._load()
+        return self
+
+
+class DerivedRegistry(Mapping):
+    """A mapping computed from another registry the first time it is used."""
+
+    __slots__ = ("_builder", "_data")
+
+    def __init__(self, builder: Callable[[], Dict[str, Any]]) -> None:
+        self._builder = builder
+        self._data: Dict[str, Any] | None = None
+
+    def _load(self) -> Dict[str, Any]:
+        if self._data is None:
+            self._data = self._builder()
+        return self._data
+
+    def __getitem__(self, key: str) -> Any:
+        return self._load()[key]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._load())
+
+    def __len__(self) -> int:
+        return len(self._load())
+
+    def __contains__(self, key: object) -> bool:
+        return key in self._load()
+
+    def __repr__(self) -> str:
+        state = "unloaded" if self._data is None else f"{len(self._data)} entries"
+        return f"<DerivedRegistry ({state})>"
+
+    @property
+    def loaded(self) -> bool:
+        return self._data is not None
+
+    def preload(self) -> "DerivedRegistry":
+        self._load()
+        return self