telethon-cli 0.1.0__py3-none-any.whl

telethon_cli/__init__.py

@@ -0,0 +1,3 @@
+from .app import main
+
+__all__ = ["main"]

telethon_cli/__main__.py

@@ -0,0 +1,5 @@
+from .app import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

telethon_cli/app.py

@@ -0,0 +1,320 @@
+import argparse
+import inspect
+import sys
+
+from .config import add_client_arguments
+from .errors import CLIError
+from .registry import discover_project_callables, discover_public_commands
+from .resolver import import_dotted_path
+from .runtime import login, logout, run_project_call, run_public_command
+from .serialization import parse_cli_value, parse_json_input, render_output
+from .settings import (
+    DEVELOPER_MODE_CONFIRMATION,
+    DEVELOPER_MODE_WARNING,
+    ProjectSettings,
+    ensure_developer_mode_enabled,
+    find_project_root,
+    get_settings_path,
+    load_project_settings,
+    save_project_settings,
+)
+
+
+MISSING = object()
+
+
+def _add_output_argument(parser):
+    parser.add_argument(
+        "--output",
+        choices=("text", "json"),
+        default="text",
+        help="Output format",
+    )
+
+
+def _add_json_arguments(parser, flag_prefix="", dest_prefix=None):
+    dest_prefix = flag_prefix if dest_prefix is None else dest_prefix
+    parser.add_argument(
+        "--{}args-json".format(flag_prefix),
+        dest="{}args_json".format(dest_prefix),
+    )
+    parser.add_argument(
+        "--{}args-file".format(flag_prefix),
+        dest="{}args_file".format(dest_prefix),
+    )
+    parser.add_argument(
+        "--{}kwargs-json".format(flag_prefix),
+        dest="{}kwargs_json".format(dest_prefix),
+    )
+    parser.add_argument(
+        "--{}kwargs-file".format(flag_prefix),
+        dest="{}kwargs_file".format(dest_prefix),
+    )
+
+
+def _load_call_arguments(namespace, prefix=""):
+    args = parse_json_input(
+        getattr(namespace, "{}args_json".format(prefix)),
+        getattr(namespace, "{}args_file".format(prefix)),
+        default=[],
+    )
+    kwargs = parse_json_input(
+        getattr(namespace, "{}kwargs_json".format(prefix)),
+        getattr(namespace, "{}kwargs_file".format(prefix)),
+        default={},
+    )
+
+    if not isinstance(args, list):
+        raise CLIError("{}args payload must decode to a list".format(prefix))
+    if not isinstance(kwargs, dict):
+        raise CLIError("{}kwargs payload must decode to an object".format(prefix))
+    return args, kwargs
+
+
+def _iter_signature_parameters(signature):
+    for param in signature.parameters.values():
+        if param.name in ("self", "cls"):
+            continue
+        if param.kind not in (
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            inspect.Parameter.KEYWORD_ONLY,
+        ):
+            continue
+        yield param
+
+
+def _merge_flag_arguments(namespace, kwargs, parameter_names):
+    for name in parameter_names:
+        value = getattr(namespace, "param_{}".format(name))
+        if value is not MISSING:
+            kwargs[name] = value
+
+
+def _handle_public_command(namespace):
+    args, kwargs = _load_call_arguments(namespace)
+    _merge_flag_arguments(namespace, kwargs, namespace.parameter_names)
+    return run_public_command(namespace, namespace.public_command, args, kwargs)
+
+
+def _handle_call(namespace):
+    ensure_developer_mode_enabled("call")
+    target = import_dotted_path(namespace.target, project_only=True)
+    args, kwargs = _load_call_arguments(namespace)
+    init_args, init_kwargs = _load_call_arguments(namespace, prefix="init_")
+    return run_project_call(
+        namespace,
+        target,
+        method_name=namespace.method,
+        init_args=init_args,
+        init_kwargs=init_kwargs,
+        args=args,
+        kwargs=kwargs,
+        client_invoke=namespace.client_invoke,
+    )
+
+
+def _handle_registry_public(_namespace):
+    return [
+        {
+            "group": command.group,
+            "command": command.cli_name,
+            "method": command.name,
+            "path": command.dotted_path,
+        }
+        for command in discover_public_commands()
+    ]
+
+
+def _handle_auth_login(namespace):
+    return login(namespace)
+
+
+def _handle_auth_logout(namespace):
+    return logout(namespace)
+
+
+def _project_settings_payload(settings):
+    return {
+        "project_root": str(find_project_root()),
+        "settings_path": str(get_settings_path()),
+        "developer_mode": settings.developer_mode,
+    }
+
+
+def _confirm_developer_mode_enable(namespace):
+    if namespace.accept_dangerous_features:
+        return
+
+    if not sys.stdin.isatty():
+        raise CLIError(
+            "Enabling developer mode requires explicit confirmation with "
+            "--accept-dangerous-features. {}".format(DEVELOPER_MODE_WARNING)
+        )
+
+    print(DEVELOPER_MODE_WARNING, file=sys.stderr)
+    print(
+        "Type '{}' to continue: ".format(DEVELOPER_MODE_CONFIRMATION),
+        file=sys.stderr,
+        end="",
+    )
+    response = sys.stdin.readline().strip()
+    if response != DEVELOPER_MODE_CONFIRMATION:
+        raise CLIError("Developer mode was not enabled")
+
+
+def _handle_settings_show(_namespace):
+    return _project_settings_payload(load_project_settings())
+
+
+def _handle_settings_developer_mode(namespace):
+    current = load_project_settings()
+    if namespace.enable and current.developer_mode:
+        return _project_settings_payload(current)
+
+    if namespace.enable:
+        _confirm_developer_mode_enable(namespace)
+        settings = ProjectSettings(developer_mode=True)
+    else:
+        settings = ProjectSettings(developer_mode=False)
+
+    save_project_settings(settings)
+    return _project_settings_payload(settings)
+
+
+def _handle_registry_project(namespace):
+    ensure_developer_mode_enabled("registry project")
+    records = discover_project_callables()
+    if namespace.prefix:
+        records = [record for record in records if record.dotted_path.startswith(namespace.prefix)]
+    output = []
+    for record in records:
+        item = {
+            "path": record.dotted_path,
+            "kind": record.kind,
+        }
+        if record.method_name:
+            item["method"] = record.method_name
+        output.append(item)
+    return output
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(prog="telethon-cli")
+    subparsers = parser.add_subparsers(dest="command")
+
+    public_commands = discover_public_commands()
+    grouped = {}
+    for command in public_commands:
+        grouped.setdefault(command.group, []).append(command)
+
+    for group, commands in grouped.items():
+        group_parser = subparsers.add_parser(group, help="{} commands".format(group))
+        group_subparsers = group_parser.add_subparsers(dest="{}_command".format(group))
+        for command in commands:
+            command_parser = group_subparsers.add_parser(
+                command.cli_name,
+                help=command.summary or command.name,
+                description=command.summary or command.dotted_path,
+            )
+            add_client_arguments(command_parser)
+            _add_output_argument(command_parser)
+            _add_json_arguments(command_parser)
+
+            parameter_names = []
+            for param in _iter_signature_parameters(command.signature):
+                parameter_names.append(param.name)
+                command_parser.add_argument(
+                    "--{}".format(param.name.replace("_", "-")),
+                    dest="param_{}".format(param.name),
+                    default=MISSING,
+                    type=parse_cli_value,
+                )
+
+            command_parser.set_defaults(
+                handler=_handle_public_command,
+                public_command=command,
+                parameter_names=tuple(parameter_names),
+            )
+
+    call_parser = subparsers.add_parser("call", help="Invoke any telethon/telethon_generator callable")
+    call_parser.add_argument("target", help="Dotted path under telethon or telethon_generator")
+    call_parser.add_argument("--method", help="Method name when the target is a class")
+    call_parser.add_argument(
+        "--client-invoke",
+        action="store_true",
+        help="Instantiate/call the target and invoke the result through TelegramClient",
+    )
+    add_client_arguments(call_parser)
+    _add_output_argument(call_parser)
+    _add_json_arguments(call_parser)
+    _add_json_arguments(call_parser, flag_prefix="init-", dest_prefix="init_")
+    call_parser.set_defaults(handler=_handle_call)
+
+    registry_parser = subparsers.add_parser("registry", help="Inspect discovered CLI coverage")
+    _add_output_argument(registry_parser)
+    registry_subparsers = registry_parser.add_subparsers(dest="registry_command")
+
+    public_parser = registry_subparsers.add_parser("public", help="List public TelegramClient commands")
+    _add_output_argument(public_parser)
+    public_parser.set_defaults(handler=_handle_registry_public)
+
+    project_parser = registry_subparsers.add_parser("project", help="List discovered project callables")
+    _add_output_argument(project_parser)
+    project_parser.add_argument("--prefix", help="Filter dotted paths by prefix")
+    project_parser.set_defaults(handler=_handle_registry_project)
+
+    login_parser = subparsers.add_parser("login", help="Create or refresh a Telegram session")
+    add_client_arguments(login_parser)
+    _add_output_argument(login_parser)
+    login_parser.set_defaults(handler=_handle_auth_login)
+
+    logout_parser = subparsers.add_parser("logout", help="Log out and remove the saved Telegram session")
+    add_client_arguments(logout_parser)
+    _add_output_argument(logout_parser)
+    logout_parser.set_defaults(handler=_handle_auth_logout)
+
+    settings_parser = subparsers.add_parser("settings", help="Manage project settings")
+    settings_subparsers = settings_parser.add_subparsers(dest="settings_command")
+
+    settings_show_parser = settings_subparsers.add_parser("show", help="Show project settings")
+    _add_output_argument(settings_show_parser)
+    settings_show_parser.set_defaults(handler=_handle_settings_show)
+
+    developer_mode_parser = settings_subparsers.add_parser(
+        "developer-mode",
+        help="Enable or disable project-wide developer mode",
+    )
+    _add_output_argument(developer_mode_parser)
+    action_group = developer_mode_parser.add_mutually_exclusive_group(required=True)
+    action_group.add_argument("--enable", action="store_true", help="Enable developer mode")
+    action_group.add_argument("--disable", action="store_true", help="Disable developer mode")
+    developer_mode_parser.add_argument(
+        "--accept-dangerous-features",
+        action="store_true",
+        help="Confirm that you understand developer mode enables dangerous features",
+    )
+    developer_mode_parser.set_defaults(handler=_handle_settings_developer_mode)
+
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    namespace = parser.parse_args(argv)
+    if not hasattr(namespace, "handler"):
+        parser.print_help(sys.stderr)
+        return 1
+
+    try:
+        result = namespace.handler(namespace)
+    except CLIError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        print("Interrupted", file=sys.stderr)
+        return 130
+
+    output = render_output(result, getattr(namespace, "output", "text"))
+    if output:
+        print(output)
+    return 0

telethon_cli/command_matrix.py

@@ -0,0 +1,106 @@
+from dataclasses import dataclass
+
+
+MODE_LIVE_SAFE = "live-safe"
+MODE_LIVE_DISPOSABLE = "live-disposable"
+MODE_MOCKED = "mocked"
+MODE_EXCLUDED_LIVE = "excluded-live"
+LIVE_MODES = frozenset({MODE_LIVE_SAFE, MODE_LIVE_DISPOSABLE})
+NON_LIVE_MODES = frozenset({MODE_MOCKED, MODE_EXCLUDED_LIVE})
+
+
+@dataclass(frozen=True)
+class CommandTestSpec:
+    group: str
+    cli_name: str
+    mode: str
+    fixture: str
+    cleanup: str
+    reason: str = ""
+
+    @property
+    def key(self):
+        return (self.group, self.cli_name)
+
+    @property
+    def method_name(self):
+        return self.cli_name.replace("-", "_")
+
+
+def _spec(group, cli_name, mode, fixture, cleanup, reason=""):
+    return CommandTestSpec(
+        group=group,
+        cli_name=cli_name,
+        mode=mode,
+        fixture=fixture,
+        cleanup=cleanup,
+        reason=reason,
+    )
+
+
+PUBLIC_COMMAND_MATRIX = (
+    _spec("auth", "start", MODE_EXCLUDED_LIVE, "none", "none", "auth-state-change"),
+    _spec("auth", "sign-in", MODE_EXCLUDED_LIVE, "none", "none", "auth-state-change"),
+    _spec("auth", "sign-up", MODE_EXCLUDED_LIVE, "none", "none", "auth-state-change"),
+    _spec("auth", "send-code-request", MODE_EXCLUDED_LIVE, "none", "none", "auth-state-change"),
+    _spec("auth", "qr-login", MODE_EXCLUDED_LIVE, "none", "none", "auth-state-change"),
+    _spec("auth", "log-out", MODE_EXCLUDED_LIVE, "none", "none", "auth-state-change"),
+    _spec("auth", "edit-2fa", MODE_EXCLUDED_LIVE, "none", "none", "security-state-change"),
+    _spec("base", "connect", MODE_LIVE_SAFE, "none", "none"),
+    _spec("base", "is-connected", MODE_LIVE_SAFE, "none", "none"),
+    _spec("base", "disconnect", MODE_LIVE_SAFE, "none", "none"),
+    _spec("base", "set-proxy", MODE_MOCKED, "none", "none", "local-network-config"),
+    _spec("messages", "iter-messages", MODE_LIVE_SAFE, "me", "none"),
+    _spec("messages", "get-messages", MODE_LIVE_SAFE, "me", "none"),
+    _spec("messages", "send-message", MODE_LIVE_DISPOSABLE, "me", "delete-created-message"),
+    _spec("messages", "forward-messages", MODE_LIVE_DISPOSABLE, "disposable-message", "delete-created-message"),
+    _spec("messages", "edit-message", MODE_LIVE_DISPOSABLE, "disposable-message", "none"),
+    _spec("messages", "delete-messages", MODE_LIVE_DISPOSABLE, "disposable-message", "handled-in-command"),
+    _spec("messages", "send-read-acknowledge", MODE_LIVE_DISPOSABLE, "disposable-message", "none"),
+    _spec("messages", "pin-message", MODE_LIVE_DISPOSABLE, "disposable-message", "restore-unpinned-state"),
+    _spec("messages", "unpin-message", MODE_LIVE_DISPOSABLE, "disposable-message", "none"),
+    _spec("uploads", "send-file", MODE_LIVE_DISPOSABLE, "temp-file", "delete-created-message"),
+    _spec("uploads", "upload-file", MODE_LIVE_DISPOSABLE, "temp-file", "delete-temp-file"),
+    _spec("downloads", "download-profile-photo", MODE_LIVE_DISPOSABLE, "me", "delete-temp-file"),
+    _spec("downloads", "download-media", MODE_MOCKED, "none", "none", "requires-message-object"),
+    _spec("downloads", "download-file", MODE_MOCKED, "none", "none", "requires-input-location"),
+    _spec("downloads", "iter-download", MODE_MOCKED, "none", "none", "requires-input-location"),
+    _spec("dialogs", "iter-dialogs", MODE_LIVE_SAFE, "none", "none"),
+    _spec("dialogs", "get-dialogs", MODE_LIVE_SAFE, "none", "none"),
+    _spec("dialogs", "iter-drafts", MODE_LIVE_SAFE, "me", "none"),
+    _spec("dialogs", "get-drafts", MODE_LIVE_SAFE, "me", "none"),
+    _spec("dialogs", "edit-folder", MODE_EXCLUDED_LIVE, "none", "none", "mutates-dialog-state"),
+    _spec("dialogs", "delete-dialog", MODE_EXCLUDED_LIVE, "none", "none", "destructive-dialog-state"),
+    _spec("dialogs", "conversation", MODE_MOCKED, "none", "none", "interactive-conversation-loop"),
+    _spec("users", "get-me", MODE_LIVE_SAFE, "none", "none"),
+    _spec("users", "is-bot", MODE_LIVE_SAFE, "none", "none"),
+    _spec("users", "is-user-authorized", MODE_LIVE_SAFE, "none", "none"),
+    _spec("users", "get-entity", MODE_LIVE_SAFE, "me", "none"),
+    _spec("users", "get-input-entity", MODE_LIVE_SAFE, "me", "none"),
+    _spec("users", "get-peer-id", MODE_LIVE_SAFE, "me", "none"),
+    _spec("chats", "iter-participants", MODE_MOCKED, "none", "none", "requires-chat-fixture"),
+    _spec("chats", "get-participants", MODE_MOCKED, "none", "none", "requires-chat-fixture"),
+    _spec("chats", "iter-admin-log", MODE_MOCKED, "none", "none", "requires-admin-chat"),
+    _spec("chats", "get-admin-log", MODE_MOCKED, "none", "none", "requires-admin-chat"),
+    _spec("chats", "iter-profile-photos", MODE_MOCKED, "none", "none", "requires-peer-fixture"),
+    _spec("chats", "get-profile-photos", MODE_MOCKED, "none", "none", "requires-peer-fixture"),
+    _spec("chats", "action", MODE_MOCKED, "none", "none", "ephemeral-side-effect"),
+    _spec("chats", "edit-admin", MODE_EXCLUDED_LIVE, "none", "none", "mutates-admin-state"),
+    _spec("chats", "edit-permissions", MODE_EXCLUDED_LIVE, "none", "none", "mutates-permissions-state"),
+    _spec("chats", "kick-participant", MODE_EXCLUDED_LIVE, "none", "none", "destructive-membership-state"),
+    _spec("chats", "get-permissions", MODE_MOCKED, "none", "none", "requires-chat-fixture"),
+    _spec("chats", "get-stats", MODE_MOCKED, "none", "none", "requires-channel-stats"),
+    _spec("updates", "set-receive-updates", MODE_MOCKED, "none", "none", "mutates-session-update-state"),
+    _spec("updates", "run-until-disconnected", MODE_MOCKED, "none", "none", "long-running-loop"),
+    _spec("updates", "on", MODE_MOCKED, "none", "none", "callback-registration"),
+    _spec("updates", "add-event-handler", MODE_MOCKED, "none", "none", "callback-registration"),
+    _spec("updates", "remove-event-handler", MODE_MOCKED, "none", "none", "callback-registration"),
+    _spec("updates", "list-event-handlers", MODE_MOCKED, "none", "none", "callback-registration"),
+    _spec("updates", "catch-up", MODE_MOCKED, "none", "none", "requires-update-queue"),
+    _spec("bots", "inline-query", MODE_MOCKED, "none", "none", "requires-inline-bot"),
+    _spec("buttons", "build-reply-markup", MODE_MOCKED, "none", "none", "pure-builder"),
+    _spec("account", "takeout", MODE_EXCLUDED_LIVE, "none", "none", "account-export-state"),
+    _spec("account", "end-takeout", MODE_EXCLUDED_LIVE, "none", "none", "account-export-state"),
+)
+
+PUBLIC_COMMAND_MATRIX_BY_KEY = {spec.key: spec for spec in PUBLIC_COMMAND_MATRIX}

telethon_cli/config.py

@@ -0,0 +1,195 @@
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import shlex
+
+from .errors import CLIError
+from .settings import find_project_root
+
+
+ENV_API_ID = "TELETHON_API_ID"
+ENV_API_HASH = "TELETHON_API_HASH"
+ENV_SESSION = "TELETHON_SESSION"
+ENV_PASSWORD = "TELETHON_PASSWORD"
+SUPPORTED_ENV_KEYS = (ENV_API_ID, ENV_API_HASH, ENV_SESSION, ENV_PASSWORD)
+DEFAULT_ENV_FILE_NAME = ".env"
+DEFAULT_SESSION_DIR_NAME = ".telethon-cli"
+DEFAULT_SESSION_FILE_NAME = "session"
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    api_id: int
+    api_hash: str
+    session: str
+    password: str = None
+
+
+def add_client_arguments(parser):
+    parser.add_argument("--api-id", dest="api_id", type=int, help="Telegram API ID")
+    parser.add_argument("--api-hash", dest="api_hash", help="Telegram API hash")
+    parser.add_argument("--session", dest="session", help="Telethon session name or path")
+    parser.add_argument("--2fa-password", dest="password", help="Telegram 2FA password")
+    parser.add_argument(
+        "--env-file",
+        dest="env_file",
+        help="Path to a dotenv file with Telethon credentials",
+    )
+
+
+def _strip_inline_comment(raw_value):
+    in_single = False
+    in_double = False
+    escaped = False
+
+    for index, char in enumerate(raw_value):
+        if escaped:
+            escaped = False
+            continue
+        if char == "\\":
+            escaped = True
+            continue
+        if char == "'" and not in_double:
+            in_single = not in_single
+            continue
+        if char == '"' and not in_single:
+            in_double = not in_double
+            continue
+        if char == "#" and not in_single and not in_double:
+            if index == 0 or raw_value[index - 1].isspace():
+                return raw_value[:index].rstrip()
+    return raw_value.strip()
+
+
+def _parse_dotenv_value(raw_value, path, line_number):
+    value = _strip_inline_comment(raw_value).strip()
+    if not value:
+        return ""
+
+    if value[0] in ("'", '"'):
+        try:
+            parsed = shlex.split(value, posix=True)
+        except ValueError as exc:
+            raise CLIError(
+                "Invalid dotenv value for line {} in '{}': {}".format(line_number, path, exc)
+            ) from exc
+        if len(parsed) != 1:
+            raise CLIError(
+                "Invalid dotenv value for line {} in '{}': {}".format(
+                    line_number,
+                    path,
+                    raw_value.strip(),
+                )
+            )
+        return parsed[0]
+
+    return value
+
+
+def _load_dotenv_file(path):
+    values = {}
+    try:
+        content = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise CLIError("Unable to read env file '{}': {}".format(path, exc)) from exc
+
+    for line_number, raw_line in enumerate(content.splitlines(), start=1):
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in raw_line:
+            raise CLIError("Invalid dotenv line {} in '{}': {}".format(line_number, path, raw_line))
+
+        key, raw_value = raw_line.split("=", 1)
+        key = key.strip()
+        if key.startswith("export "):
+            key = key[len("export "):].strip()
+        if not key:
+            raise CLIError("Invalid dotenv line {} in '{}': {}".format(line_number, path, raw_line))
+        if key not in SUPPORTED_ENV_KEYS:
+            continue
+        values[key] = _parse_dotenv_value(raw_value, path, line_number)
+
+    return values
+
+
+def _resolve_env_file(namespace):
+    explicit_path = getattr(namespace, "env_file", None)
+    if explicit_path:
+        path = Path(explicit_path).expanduser()
+        if not path.is_absolute():
+            path = Path.cwd() / path
+        path = path.resolve()
+        if not path.exists():
+            raise CLIError("Env file '{}' does not exist".format(path))
+        if path.is_dir():
+            raise CLIError("Env file '{}' must be a file".format(path))
+        return path
+
+    candidates = []
+    cwd_path = (Path.cwd() / DEFAULT_ENV_FILE_NAME).resolve()
+    candidates.append(cwd_path)
+
+    project_root_path = (find_project_root() / DEFAULT_ENV_FILE_NAME).resolve()
+    if project_root_path not in candidates:
+        candidates.append(project_root_path)
+
+    for candidate in candidates:
+        if candidate.exists() and candidate.is_file():
+            return candidate
+    return None
+
+
+def _merge_environment(environ, dotenv_values, dotenv_path):
+    merged = dict(environ)
+    conflicts = []
+
+    for key, dotenv_value in dotenv_values.items():
+        env_value = environ.get(key)
+        if env_value is None:
+            merged[key] = dotenv_value
+            continue
+        if env_value != dotenv_value:
+            conflicts.append("{} (environment vs {})".format(key, dotenv_path))
+
+    if conflicts:
+        raise CLIError(
+            "Conflicting Telethon client config values: {}".format(", ".join(conflicts))
+        )
+
+    return merged
+
+
+def _default_session_path(start_path=None):
+    project_root = find_project_root(start_path)
+    return project_root / DEFAULT_SESSION_DIR_NAME / DEFAULT_SESSION_FILE_NAME
+
+
+def load_client_config(namespace, environ=None):
+    environ = os.environ if environ is None else environ
+    dotenv_path = _resolve_env_file(namespace)
+    if dotenv_path is not None:
+        environ = _merge_environment(environ, _load_dotenv_file(dotenv_path), dotenv_path)
+
+    api_id = namespace.api_id if getattr(namespace, "api_id", None) is not None else environ.get(ENV_API_ID)
+    api_hash = namespace.api_hash if getattr(namespace, "api_hash", None) is not None else environ.get(ENV_API_HASH)
+    session = namespace.session if getattr(namespace, "session", None) is not None else environ.get(ENV_SESSION)
+    password = namespace.password if getattr(namespace, "password", None) is not None else environ.get(ENV_PASSWORD)
+
+    missing = []
+    if api_id in (None, ""):
+        missing.append(ENV_API_ID)
+    if not api_hash:
+        missing.append(ENV_API_HASH)
+    if missing:
+        raise CLIError("Missing Telethon client config: {}".format(", ".join(missing)))
+
+    try:
+        api_id = int(api_id)
+    except (TypeError, ValueError) as exc:
+        raise CLIError("{} must be an integer".format(ENV_API_ID)) from exc
+
+    if not session:
+        session = str(_default_session_path())
+
+    return ClientConfig(api_id=api_id, api_hash=api_hash, session=session, password=password)

telethon_cli/errors.py

@@ -0,0 +1,2 @@
+class CLIError(Exception):
+    """Raised for recoverable CLI errors."""