telethon-cli 0.1.0__py3-none-any.whl

telethon_cli/runtime.py

@@ -0,0 +1,280 @@
+import asyncio
+import getpass
+import inspect
+from pathlib import Path
+import sys
+
+from telethon import TelegramClient
+
+from .config import load_client_config
+from .errors import CLIError
+
+try:
+    from telethon.tl.tlobject import TLRequest
+except ImportError:  # pragma: no cover - covered once bootstrap runs
+    TLRequest = None
+
+try:
+    from telethon.errors import SessionPasswordNeededError
+except ImportError:  # pragma: no cover - covered once bootstrap runs
+    SessionPasswordNeededError = None
+
+
+NO_AUTO_CONNECT_METHODS = frozenset({
+    "connect",
+    "disconnect",
+    "is_connected",
+    "set_proxy",
+})
+
+
+def _validate_call(target, args, kwargs, label):
+    try:
+        signature = inspect.signature(target)
+    except (TypeError, ValueError):
+        return
+
+    try:
+        signature.bind(*args, **kwargs)
+    except TypeError as exc:
+        raise CLIError("Invalid arguments for {}: {}".format(label, exc)) from exc
+
+
+async def _maybe_await(value):
+    if inspect.isawaitable(value):
+        value = await value
+    if hasattr(value, "__aiter__"):
+        return [item async for item in value]
+    return value
+
+
+def _run(value):
+    if inspect.isawaitable(value):
+        return asyncio.run(value)
+    return value
+
+
+def _session_exists(session):
+    session_path = Path(session)
+    if session_path.exists():
+        return True
+    if session_path.suffix:
+        return False
+    return session_path.with_suffix(".session").exists()
+
+
+def _ensure_session_directory(session):
+    session_path = Path(session)
+    directory = session_path.parent
+    if not directory:
+        return
+    directory.mkdir(parents=True, exist_ok=True)
+
+
+def _session_file_paths(session):
+    session_path = Path(session)
+    db_path = session_path if session_path.suffix else session_path.with_suffix(".session")
+    return (
+        db_path,
+        Path(str(db_path) + "-journal"),
+        Path(str(db_path) + "-shm"),
+        Path(str(db_path) + "-wal"),
+    )
+
+
+def _remove_session_files(session):
+    removed = []
+    for path in _session_file_paths(session):
+        if not path.exists():
+            continue
+        path.unlink()
+        removed.append(str(path))
+    return removed
+
+
+def _prompt(label, *, secret=False):
+    if not sys.stdin.isatty():
+        raise CLIError("Interactive authentication requires a TTY")
+    if secret:
+        return getpass.getpass(label)
+    print(label, file=sys.stderr, end="", flush=True)
+    return sys.stdin.readline().strip()
+
+
+async def _authorize_client(client, namespace):
+    if await client.is_user_authorized():
+        return client
+
+    if not sys.stdin.isatty():
+        raise CLIError(
+            "No saved Telegram session was found and interactive login requires a TTY. "
+            "Run `telethon-cli login` in an interactive terminal first."
+        )
+
+    phone = _prompt("Telegram phone number: ")
+    if not phone:
+        raise CLIError("Telegram phone number is required")
+
+    sent = await client.send_code_request(phone)
+    code = _prompt("Telegram login code: ")
+    if not code:
+        raise CLIError("Telegram login code is required")
+
+    try:
+        await client.sign_in(phone=phone, code=code, phone_code_hash=sent.phone_code_hash)
+    except Exception as exc:
+        if SessionPasswordNeededError is None or not isinstance(exc, SessionPasswordNeededError):
+            raise
+        password = load_client_config(namespace).password
+        if not password:
+            password = _prompt("Telegram 2FA password: ", secret=True)
+        if not password:
+            raise CLIError("Telegram 2FA password is required")
+        await client.sign_in(password=password)
+
+    if not await client.is_user_authorized():
+        raise CLIError("Telegram login failed")
+    return client
+
+
+def create_client(namespace):
+    config = load_client_config(namespace)
+    _ensure_session_directory(config.session)
+    return TelegramClient(config.session, config.api_id, config.api_hash)
+
+
+async def _authorized_client(namespace, *, allow_interactive_login=True):
+    client = create_client(namespace)
+    await client.connect()
+    if await client.is_user_authorized():
+        return client
+
+    if not allow_interactive_login:
+        await client.disconnect()
+        raise CLIError(
+            "No saved Telegram session was found for '{}'. Run `telethon-cli login` first."
+            .format(load_client_config(namespace).session)
+        )
+
+    try:
+        return await _authorize_client(client, namespace)
+    except Exception:
+        await client.disconnect()
+        raise
+
+
+def login(namespace):
+    return _run(_login_async(namespace))
+
+
+async def _login_async(namespace):
+    client = await _authorized_client(namespace, allow_interactive_login=True)
+    session = load_client_config(namespace).session
+    try:
+        return {
+            "authorized": True,
+            "session": session,
+        }
+    finally:
+        await client.disconnect()
+
+
+def logout(namespace):
+    return _run(_logout_async(namespace))
+
+
+async def _logout_async(namespace):
+    session = load_client_config(namespace).session
+    if not _session_exists(session):
+        return {
+            "authorized": False,
+            "logged_out": False,
+            "session": session,
+        }
+
+    client = create_client(namespace)
+    logged_out = False
+    try:
+        await client.connect()
+        if await client.is_user_authorized():
+            logged_out = await client.log_out()
+    finally:
+        await client.disconnect()
+
+    removed_files = _remove_session_files(session)
+    return {
+        "authorized": False,
+        "logged_out": bool(logged_out or removed_files),
+        "session": session,
+    }
+
+
+async def _invoke_request_with_client(namespace, request):
+    if TLRequest is not None and not isinstance(request, TLRequest):
+        raise CLIError("Client invocation expects a TLRequest instance")
+
+    client = await _authorized_client(namespace)
+    try:
+        return await client(request)
+    finally:
+        await client.disconnect()
+
+
+async def _run_public_command_async(namespace, command, args, kwargs):
+    if command.name in NO_AUTO_CONNECT_METHODS:
+        client = create_client(namespace)
+    else:
+        client = await _authorized_client(namespace)
+
+    try:
+        method = getattr(client, command.name)
+        _validate_call(method, args, kwargs, command.dotted_path)
+        return await _maybe_await(method(*args, **kwargs))
+    finally:
+        await client.disconnect()
+
+
+def run_public_command(namespace, command, args, kwargs):
+    return _run(_run_public_command_async(namespace, command, args, kwargs))
+
+
+def run_project_call(namespace, target, *, method_name=None, init_args=None,
+                     init_kwargs=None, args=None, kwargs=None, client_invoke=False):
+    init_args = [] if init_args is None else init_args
+    init_kwargs = {} if init_kwargs is None else init_kwargs
+    args = [] if args is None else args
+    kwargs = {} if kwargs is None else kwargs
+
+    if inspect.isclass(target):
+        _validate_call(target, init_args, init_kwargs, "{}.__init__".format(target.__qualname__))
+        instance = target(*init_args, **init_kwargs)
+
+        if method_name:
+            method = getattr(instance, method_name, None)
+            if method is None:
+                raise CLIError("Class '{}' has no method '{}'".format(target.__qualname__, method_name))
+            if not callable(method):
+                raise CLIError("'{}' on '{}' is not callable".format(method_name, target.__qualname__))
+            _validate_call(method, args, kwargs, "{}.{}".format(target.__qualname__, method_name))
+            return _run(method(*args, **kwargs))
+
+        if client_invoke:
+            return _run(_invoke_request_with_client(namespace, instance))
+
+        return instance
+
+    if client_invoke:
+        if callable(target):
+            _validate_call(target, args, kwargs, getattr(target, "__qualname__", repr(target)))
+            request = _run(target(*args, **kwargs))
+        else:
+            request = target
+        return _run(_invoke_request_with_client(namespace, request))
+
+    if callable(target):
+        _validate_call(target, args, kwargs, getattr(target, "__qualname__", repr(target)))
+        return _run(target(*args, **kwargs))
+
+    if args or kwargs or init_args or init_kwargs or method_name:
+        raise CLIError("Target '{}' is not callable".format(target))
+    return target

telethon_cli/serialization.py

@@ -0,0 +1,141 @@
+import dataclasses
+import inspect
+import json
+from pathlib import Path
+
+from .errors import CLIError
+from .resolver import import_dotted_path
+from .settings import ensure_developer_mode_enabled
+
+try:
+    from telethon.tl.tlobject import TLObject
+except ImportError:  # pragma: no cover - covered once bootstrap runs
+    TLObject = None
+
+
+def _call_from_spec(spec):
+    if not isinstance(spec, dict) or "path" not in spec:
+        raise CLIError("$call payload must be an object with a 'path' field")
+
+    args = materialize_payload(spec.get("args", []))
+    kwargs = materialize_payload(spec.get("kwargs", {}))
+    if not isinstance(args, list):
+        raise CLIError("$call args must decode to a list")
+    if not isinstance(kwargs, dict):
+        raise CLIError("$call kwargs must decode to an object")
+
+    target = import_dotted_path(spec["path"], project_only=False)
+    try:
+        result = target(*args, **kwargs)
+    except (AttributeError, ImportError, TypeError, ValueError) as exc:
+        raise CLIError("Failed to materialize '$call' for '{}': {}".format(spec["path"], exc)) from exc
+
+    if inspect.isawaitable(result):
+        raise CLIError("Awaitable '$call' values are not supported in JSON payloads")
+
+    return result
+
+
+def materialize_payload(value):
+    if isinstance(value, list):
+        return [materialize_payload(item) for item in value]
+
+    if isinstance(value, dict):
+        if set(value) == {"$ref"}:
+            ensure_developer_mode_enabled("JSON $ref materialization")
+            return import_dotted_path(value["$ref"], project_only=False)
+        if set(value) == {"$call"}:
+            ensure_developer_mode_enabled("JSON $call materialization")
+            return _call_from_spec(value["$call"])
+        return {key: materialize_payload(item) for key, item in value.items()}
+
+    return value
+
+
+def parse_json_input(text=None, file_path=None, *, default):
+    if text and file_path:
+        raise CLIError("Use either inline JSON or a JSON file, not both")
+    if text is None and file_path is None:
+        return default
+
+    if file_path:
+        try:
+            raw = Path(file_path).read_text(encoding="utf-8")
+        except OSError as exc:
+            raise CLIError("Unable to read JSON file '{}': {}".format(file_path, exc)) from exc
+    else:
+        raw = text
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise CLIError("Invalid JSON payload: {}".format(exc)) from exc
+    return materialize_payload(payload)
+
+
+def parse_cli_value(value):
+    try:
+        decoded = json.loads(value)
+    except json.JSONDecodeError:
+        return value
+    return materialize_payload(decoded)
+
+
+def _serialize_iterable(value):
+    if isinstance(value, dict):
+        return {str(key): serialize_result(item) for key, item in value.items()}
+
+    if isinstance(value, (list, tuple, set)):
+        return [serialize_result(item) for item in value]
+
+    return None
+
+
+def _serialize_instance(value):
+    to_dict = getattr(value, "to_dict", None)
+    if callable(to_dict):
+        return serialize_result(to_dict())
+
+    if callable(value):
+        module = getattr(value, "__module__", None) or type(value).__module__
+        qualname = getattr(value, "__qualname__", type(value).__qualname__)
+        return {"__callable__": "{}.{}".format(module, qualname)}
+
+    if hasattr(value, "__dict__"):
+        return {
+            "__class__": "{}.{}".format(type(value).__module__, type(value).__qualname__),
+            "attributes": serialize_result(vars(value)),
+        }
+
+    return str(value)
+
+
+def serialize_result(value):
+    if dataclasses.is_dataclass(value):
+        return serialize_result(dataclasses.asdict(value))
+
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return value
+
+    if isinstance(value, bytes):
+        return {"__type__": "bytes", "hex": value.hex()}
+
+    if isinstance(value, Path):
+        return str(value)
+
+    if TLObject and isinstance(value, TLObject):
+        return serialize_result(value.to_dict())
+
+    iterable = _serialize_iterable(value)
+    if iterable is not None:
+        return iterable
+
+    return _serialize_instance(value)
+
+
+def render_output(value, output_format):
+    rendered = serialize_result(value)
+    if output_format == "json":
+        return json.dumps(rendered, indent=2, sort_keys=True, ensure_ascii=False)
+    if isinstance(rendered, str):
+        return rendered
+    return json.dumps(rendered, indent=2, sort_keys=True, ensure_ascii=False)

telethon_cli/settings.py

@@ -0,0 +1,81 @@
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import CLIError
+
+
+SETTINGS_FILE_NAME = ".telethon-cli.json"
+DEVELOPER_MODE_CONFIRMATION = "enable developer mode"
+DEVELOPER_MODE_WARNING = (
+    "Developer mode enables dangerous features, including internal callable "
+    "dispatch and JSON materialization helpers. Enable it only if you "
+    "understand and accept the risk."
+)
+
+
+@dataclass(frozen=True)
+class ProjectSettings:
+    developer_mode: bool = False
+
+
+def find_project_root(start_path=None):
+    current = Path.cwd() if start_path is None else Path(start_path)
+    current = current.resolve()
+    if current.is_file():
+        current = current.parent
+
+    for candidate in (current,) + tuple(current.parents):
+        if (candidate / ".git").exists() or (candidate / "pyproject.toml").exists():
+            return candidate
+    return current
+
+
+def get_settings_path(start_path=None):
+    return find_project_root(start_path) / SETTINGS_FILE_NAME
+
+
+def load_project_settings(start_path=None):
+    path = get_settings_path(start_path)
+    if not path.exists():
+        return ProjectSettings()
+
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise CLIError("Unable to read settings file '{}': {}".format(path, exc)) from exc
+    except json.JSONDecodeError as exc:
+        raise CLIError("Invalid settings file '{}': {}".format(path, exc)) from exc
+
+    if not isinstance(payload, dict):
+        raise CLIError("Settings file '{}' must contain a JSON object".format(path))
+
+    developer_mode = payload.get("developer_mode", False)
+    if not isinstance(developer_mode, bool):
+        raise CLIError("Setting 'developer_mode' in '{}' must be a boolean".format(path))
+
+    return ProjectSettings(developer_mode=developer_mode)
+
+
+def save_project_settings(settings, start_path=None):
+    path = get_settings_path(start_path)
+    payload = {
+        "developer_mode": settings.developer_mode,
+    }
+    try:
+        path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    except OSError as exc:
+        raise CLIError("Unable to write settings file '{}': {}".format(path, exc)) from exc
+    return path
+
+
+def ensure_developer_mode_enabled(feature_name, start_path=None):
+    settings = load_project_settings(start_path)
+    if settings.developer_mode:
+        return
+
+    raise CLIError(
+        "{} is disabled until developer mode is enabled in project settings. "
+        "Run `telethon-cli settings developer-mode --enable "
+        "--accept-dangerous-features` after reviewing the warning.".format(feature_name)
+    )

telethon_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: telethon-cli
+Version: 0.1.0
+Summary: Command-line interface for Telethon and Telethon internals
+Author: Axisrow
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/axisrow/telethon-cli
+Project-URL: Repository, https://github.com/axisrow/telethon-cli
+Project-URL: Issues, https://github.com/axisrow/telethon-cli/issues
+Keywords: telegram,telethon,cli,api,automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: Telethon>=1
+
+# telethon-cli
+
+`telethon-cli` is a separate installable package that exposes:
+
+- a stable command tree for the public `TelegramClient` API;
+- a generic dispatcher for internal `telethon` and `telethon_generator` callables;
+- env-first client configuration through `TELETHON_API_ID` and `TELETHON_API_HASH`,
+  with optional session overrides.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+python -m pip install telethon-cli
+```
+
+For local development, install the package in editable mode:
+
+```bash
+python -m pip install -e .
+```
+
+Set the required Telethon credentials before running commands. You can export
+them directly in the shell:
+
+```bash
+export TELETHON_API_ID=...
+export TELETHON_API_HASH=...
+```
+
+You can also keep them in a `.env` file in the current working directory or at
+the project root:
+
+```dotenv
+TELETHON_API_ID=...
+TELETHON_API_HASH=...
+```
+
+On first login, `telethon-cli` can create and store a Telethon session in the
+project automatically. You can create it explicitly:
+
+```bash
+telethon-cli login
+```
+
+Typical first-run flow:
+
+```bash
+python -m pip install -e .
+telethon-cli login
+telethon-cli users get-me --output json
+```
+
+To remove the saved session and force a fresh login next time:
+
+```bash
+telethon-cli logout
+```
+
+Or just run the first command in an interactive terminal and let the CLI ask for
+your phone number, login code, and Telegram 2FA password when needed:
+
+```bash
+telethon-cli users get-me --output json
+```
+
+By default the session is stored in `.telethon-cli/session` under the project
+root. You can override it explicitly:
+
+```bash
+telethon-cli users get-me --session /path/to/session --output json
+telethon-cli users get-me --env-file /path/to/telethon.env --output json
+```
+
+`telethon-cli` reads the current process environment and also loads `.env`
+automatically when present. If the same Telethon setting is defined both in the
+environment and in `.env`, and the values differ, the command exits with an
+error instead of silently choosing one. CLI flags such as `--api-id`,
+`--api-hash`, `--session`, and `--2fa-password` still override both.
+
+In non-interactive environments, automatic login is not possible. In that case,
+create the session in advance with `telethon-cli login` and reuse it later.
+
+Smoke-test the installation:
+
+```bash
+telethon-cli --help
+python -m telethon_cli registry public --output json
+telethon-cli users get-me --output json
+```
+
+Dangerous features are gated behind project-wide developer mode. Enable it once
+from settings and explicitly confirm the warning before using `call`,
+`registry project`, `$ref`, or `$call` payload helpers:
+
+```bash
+telethon-cli settings developer-mode --enable --accept-dangerous-features
+```
+
+Examples:
+
+```bash
+telethon-cli users get-me --output json
+telethon-cli messages send-message --entity me --message "hello"
+telethon-cli call telethon.utils.parse_phone --args-json '["+1 234 567"]'
+telethon-cli call telethon.tl.functions.help.GetConfigRequest --client-invoke --output json
+telethon-cli settings show --output json
+```
+
+## Release Process
+
+Build and validate release artifacts locally before uploading:
+
+```bash
+rm -rf dist build src/*.egg-info
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+```
+
+Optional local smoke-test from the built wheel:
+
+```bash
+python -m pip install --force-reinstall dist/*.whl
+telethon-cli --help
+python -m telethon_cli registry public --output json
+```
+
+Upload to TestPyPI first:
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+Verify installation from TestPyPI:
+
+```bash
+python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple telethon-cli
+telethon-cli --help
+python -m telethon_cli registry public --output json
+```
+
+Then upload the same artifacts to PyPI:
+
+```bash
+python -m twine upload dist/*
+```
+
+When `twine` prompts for credentials, use username `__token__` and your
+`pypi-...` API token as the password. Keep PyPI tokens out of the repository
+and provide them through the environment or `twine` prompt.
+
+For every subsequent release, bump `version` in `pyproject.toml` before
+building. PyPI rejects uploads for versions that already exist.
+
+You can also keep PyPI credentials in the project-local `.env` file, because
+`.env` is gitignored in this repository. The release helper script reads `.env`
+automatically and publishes with `twine`:
+
+```dotenv
+TWINE_USERNAME=__token__
+TEST_PYPI_TOKEN=pypi-...
+PYPI_TOKEN=pypi-...
+```
+
+```bash
+chmod +x scripts/release_pypi.sh
+./scripts/release_pypi.sh testpypi
+./scripts/release_pypi.sh pypi
+./scripts/release_pypi.sh all
+```