telethon-cli 0.1.1__tar.gz → 0.1.2__tar.gz

telethon_cli-0.1.2/.env.example

@@ -0,0 +1,18 @@
+TG_API_ID=
+TG_API_HASH=
+
+# Optional: override the default project-local session path.
+# TG_SESSION=.telethon-cli/session
+
+# Optional: provide Telegram 2FA password for non-interactive auth.
+# TG_PASSWORD=
+
+# Optional: route the client through a proxy (socks5/socks4/http).
+# Requires: pip install 'telethon-cli[proxy]'
+# TG_PROXY=socks5://user:pass@host:1080
+
+# Optional: PyPI publishing credentials for scripts/release_pypi.sh.
+# Keep real tokens in your local .env only, never in version control.
+# TWINE_USERNAME=__token__
+# TEST_PYPI_TOKEN=pypi-...
+# PYPI_TOKEN=pypi-...

telethon_cli-0.1.2/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.hypothesis/
+.tox/
+.nox/
+.venv/
+venv/
+env/
+.env
+*.env
+.telethon-cli/
+.DS_Store
+._*
+build/
+dist/
+*.egg-info/

telethon_cli-0.1.2/AGENTS.md

@@ -0,0 +1,42 @@
+# Repository Guidelines
+
+`CLAUDE.md` is a symlink to this file — edit AGENTS.md, not the symlink.
+
+## Project Structure & Module Organization
+This repository is a small `src`-layout Python package. Core code lives in `src/telethon_cli/`: `app.py` builds the CLI, `runtime.py` owns Telegram client execution, `registry.py` discovers callable coverage, `serialization.py` handles JSON input/output and result serialization, `config.py` loads env-based credentials, `settings.py` manages project settings (developer mode), `resolver.py` imports dotted paths, and `command_matrix.py` + `live_smoke.py` form the live-test matrix. Package metadata and the console entry point live in `pyproject.toml`. Tests live in `tests/`, mirroring the package structure.
+
+## Commands
+- `python -m pytest` — full suite (root `conftest.py` points imports at `src/`, not the installed copy).
+- `python -m pytest tests/test_config.py` — single module; add `-k <name>` for a single test.
+- `python -m pip install -e .` — editable install for local development.
+- `python -m telethon_cli registry public --output json` — exercises the CLI without credentials.
+- `python scripts/smoke/live_public_commands.py` — live smoke over the command matrix (needs a session; the script re-invokes the CLI with `PYTHONPATH=src` itself).
+- `./scripts/release_pypi.sh testpypi|pypi|all` — release helper; reads PyPI tokens from `.env`.
+
+Live commands need `TG_API_ID`/`TG_API_HASH` (+ optionally `TG_SESSION`, `TG_PROXY`) from `.env` or the environment. On networks where MTProto is throttled, set `TG_PROXY=socks5://host:port` — needs `pip install 'telethon-cli[proxy]'`, otherwise the CLI errors out instead of silently ignoring the proxy.
+
+Do not `pip install .` (non-editable, global) to "try" changes: the globally installed copy backs the production tg-agent; reinstall it only with explicit consent. `python -m pytest` and `python -m telethon_cli ...` cover local verification.
+
+## Architecture
+The CLI surface is **generated by reflection at parser-build time**, not hand-written:
+
+1. `registry.discover_public_commands()` reflects over the Telethon client mixin classes listed in `PUBLIC_GROUP_SPECS` (`src/telethon_cli/registry.py:10`). Every public method becomes a `<group> <method-name>` command (e.g. `users get-me`), with one `--<param>` flag per signature parameter.
+2. `app.build_parser()` wires those commands, adds client flags (`--api-id`, `--session`, `--proxy`, ... via `config.add_client_arguments`) and sets a `handler` callable on each subparser; `main()` only dispatches to it and renders output. All handlers return a Python object; `serialization.render_output` serializes it (TLObject → `to_dict()`, dataclasses → dict, bytes → hex, callables → `{"__callable__": path}`, arbitrary objects → `__class__` + `vars`).
+3. `runtime.py` creates a **fresh `TelegramClient` per invocation** — connect, run, disconnect in `finally`; nothing persists between commands. Methods in `NO_AUTO_CONNECT_METHODS` skip auto-connect/auth. Awaitables are awaited and async generators drained by `_maybe_await`.
+4. Flag collision rule (`src/telethon_cli/app.py:220`): a method parameter named like a client flag (e.g. `set_proxy(proxy)`) owns the flag; the client flag is skipped for that command and connection config falls back to `TG_PROXY`.
+
+The second, dangerous layer is the generic dispatcher: `call <dotted.path>` invokes any callable under `telethon`/`telethon_generator` (`resolver.import_dotted_path` with `project_only=True`); `--client-invoke` sends the built TLRequest through the connected client. `call`, `registry project`, and the JSON `$ref`/`$call` payload helpers in `serialization.materialize_payload` are gated by `settings.ensure_developer_mode_enabled` (`.telethon-cli.json` at the project root; enabled via `settings developer-mode --enable --accept-dangerous-features`).
+
+Config precedence (`config.py`): CLI flag > `TG_*` env / `.env` > defaults; legacy `TELETHON_*` names are aliases of the `TG_*` keys. Any conflict (env vs `.env`, or two aliases with different values) is a hard `CLIError` — never silent precedence. Session defaults to `.telethon-cli/session` under the project root found by walking up to `.git`/`pyproject.toml` (`settings.find_project_root`). `CLIError` → exit code 2; interrupt → 130.
+
+## Coding Style & Naming Conventions
+Follow the existing style: 4-space indentation, `snake_case` for functions and modules, `UPPER_CASE` for constants, and kebab-case for CLI flags such as `--client-invoke`. Keep modules focused and stdlib-first where practical. Match the repository's direct, explicit error handling with `CLIError`, and prefer small helpers over deeply nested argument parsing blocks.
+
+## Testing Guidelines
+Use `pytest` and place tests in `tests/test_<module>.py`, mirroring `src/telethon_cli/`. `tests/test_command_matrix.py` asserts that `command_matrix.py` matches the discovered registry exactly — a new or renamed Telethon public method needs a matrix entry, or the suite fails. Prioritize coverage around argument binding, JSON materialization, serialization, and configuration validation. For Telethon-dependent behavior, prefer mocks (see the `_MatrixClient` pattern in `tests/test_command_matrix.py`) or the documented live smoke script rather than relying on live Telegram access in every test.
+
+## Commit & Pull Request Guidelines
+The current history uses short, imperative subjects such as `Add proxy support: TG_PROXY / --proxy (issue #3)`. Keep commits focused and use the same style. Pull requests should describe behavior changes, list verification steps, and include example CLI commands when output or arguments change.
+
+## Security & Configuration Tips
+Never commit Telegram credentials or session files. Use `TG_API_ID`, `TG_API_HASH`, and `TG_SESSION` from the environment (legacy `TELETHON_*` names are compatibility aliases only), and scrub command examples before sharing logs in issues or reviews.

telethon_cli-0.1.2/CLAUDE.md

@@ -0,0 +1,42 @@
+# Repository Guidelines
+
+`CLAUDE.md` is a symlink to this file — edit AGENTS.md, not the symlink.
+
+## Project Structure & Module Organization
+This repository is a small `src`-layout Python package. Core code lives in `src/telethon_cli/`: `app.py` builds the CLI, `runtime.py` owns Telegram client execution, `registry.py` discovers callable coverage, `serialization.py` handles JSON input/output and result serialization, `config.py` loads env-based credentials, `settings.py` manages project settings (developer mode), `resolver.py` imports dotted paths, and `command_matrix.py` + `live_smoke.py` form the live-test matrix. Package metadata and the console entry point live in `pyproject.toml`. Tests live in `tests/`, mirroring the package structure.
+
+## Commands
+- `python -m pytest` — full suite (root `conftest.py` points imports at `src/`, not the installed copy).
+- `python -m pytest tests/test_config.py` — single module; add `-k <name>` for a single test.
+- `python -m pip install -e .` — editable install for local development.
+- `python -m telethon_cli registry public --output json` — exercises the CLI without credentials.
+- `python scripts/smoke/live_public_commands.py` — live smoke over the command matrix (needs a session; the script re-invokes the CLI with `PYTHONPATH=src` itself).
+- `./scripts/release_pypi.sh testpypi|pypi|all` — release helper; reads PyPI tokens from `.env`.
+
+Live commands need `TG_API_ID`/`TG_API_HASH` (+ optionally `TG_SESSION`, `TG_PROXY`) from `.env` or the environment. On networks where MTProto is throttled, set `TG_PROXY=socks5://host:port` — needs `pip install 'telethon-cli[proxy]'`, otherwise the CLI errors out instead of silently ignoring the proxy.
+
+Do not `pip install .` (non-editable, global) to "try" changes: the globally installed copy backs the production tg-agent; reinstall it only with explicit consent. `python -m pytest` and `python -m telethon_cli ...` cover local verification.
+
+## Architecture
+The CLI surface is **generated by reflection at parser-build time**, not hand-written:
+
+1. `registry.discover_public_commands()` reflects over the Telethon client mixin classes listed in `PUBLIC_GROUP_SPECS` (`src/telethon_cli/registry.py:10`). Every public method becomes a `<group> <method-name>` command (e.g. `users get-me`), with one `--<param>` flag per signature parameter.
+2. `app.build_parser()` wires those commands, adds client flags (`--api-id`, `--session`, `--proxy`, ... via `config.add_client_arguments`) and sets a `handler` callable on each subparser; `main()` only dispatches to it and renders output. All handlers return a Python object; `serialization.render_output` serializes it (TLObject → `to_dict()`, dataclasses → dict, bytes → hex, callables → `{"__callable__": path}`, arbitrary objects → `__class__` + `vars`).
+3. `runtime.py` creates a **fresh `TelegramClient` per invocation** — connect, run, disconnect in `finally`; nothing persists between commands. Methods in `NO_AUTO_CONNECT_METHODS` skip auto-connect/auth. Awaitables are awaited and async generators drained by `_maybe_await`.
+4. Flag collision rule (`src/telethon_cli/app.py:220`): a method parameter named like a client flag (e.g. `set_proxy(proxy)`) owns the flag; the client flag is skipped for that command and connection config falls back to `TG_PROXY`.
+
+The second, dangerous layer is the generic dispatcher: `call <dotted.path>` invokes any callable under `telethon`/`telethon_generator` (`resolver.import_dotted_path` with `project_only=True`); `--client-invoke` sends the built TLRequest through the connected client. `call`, `registry project`, and the JSON `$ref`/`$call` payload helpers in `serialization.materialize_payload` are gated by `settings.ensure_developer_mode_enabled` (`.telethon-cli.json` at the project root; enabled via `settings developer-mode --enable --accept-dangerous-features`).
+
+Config precedence (`config.py`): CLI flag > `TG_*` env / `.env` > defaults; legacy `TELETHON_*` names are aliases of the `TG_*` keys. Any conflict (env vs `.env`, or two aliases with different values) is a hard `CLIError` — never silent precedence. Session defaults to `.telethon-cli/session` under the project root found by walking up to `.git`/`pyproject.toml` (`settings.find_project_root`). `CLIError` → exit code 2; interrupt → 130.
+
+## Coding Style & Naming Conventions
+Follow the existing style: 4-space indentation, `snake_case` for functions and modules, `UPPER_CASE` for constants, and kebab-case for CLI flags such as `--client-invoke`. Keep modules focused and stdlib-first where practical. Match the repository's direct, explicit error handling with `CLIError`, and prefer small helpers over deeply nested argument parsing blocks.
+
+## Testing Guidelines
+Use `pytest` and place tests in `tests/test_<module>.py`, mirroring `src/telethon_cli/`. `tests/test_command_matrix.py` asserts that `command_matrix.py` matches the discovered registry exactly — a new or renamed Telethon public method needs a matrix entry, or the suite fails. Prioritize coverage around argument binding, JSON materialization, serialization, and configuration validation. For Telethon-dependent behavior, prefer mocks (see the `_MatrixClient` pattern in `tests/test_command_matrix.py`) or the documented live smoke script rather than relying on live Telegram access in every test.
+
+## Commit & Pull Request Guidelines
+The current history uses short, imperative subjects such as `Add proxy support: TG_PROXY / --proxy (issue #3)`. Keep commits focused and use the same style. Pull requests should describe behavior changes, list verification steps, and include example CLI commands when output or arguments change.
+
+## Security & Configuration Tips
+Never commit Telegram credentials or session files. Use `TG_API_ID`, `TG_API_HASH`, and `TG_SESSION` from the environment (legacy `TELETHON_*` names are compatibility aliases only), and scrub command examples before sharing logs in issues or reviews.

{telethon_cli-0.1.1 → telethon_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telethon-cli
-Version: 0.1.1
+Version: 0.1.2
 Summary: Command-line interface for Telethon and Telethon internals
 Author: Axisrow
 License-Expression: MIT
@@ -24,6 +24,8 @@ Classifier: Topic :: Utilities
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 Requires-Dist: Telethon>=1
+Provides-Extra: proxy
+Requires-Dist: python-socks[asyncio]>=2; extra == "proxy"
 
 # telethon-cli
 
@@ -68,6 +70,47 @@ Legacy `TELETHON_API_ID`, `TELETHON_API_HASH`, `TELETHON_SESSION`, and
 `TELETHON_PASSWORD` are still accepted as compatibility aliases. When both
 namespaces are present, `telethon-cli` requires the values to match.
 
+### User config
+
+Settings that should persist across projects can live in an optional
+user-level config file at `~/.config/telethon-cli/config.json` (override the
+base directory with `XDG_CONFIG_HOME`):
+
+```json
+{
+  "api_id": 12345,
+  "api_hash": "...",
+  "session": "/path/to/session",
+  "proxy": "socks5://user:pass@host:1080"
+}
+```
+
+A missing file is not an error. Unknown keys are rejected so typos never pass
+silently, and secrets such as `api_hash` belong here or in the environment —
+never in committed files. Inspect the effective configuration, including where
+every value came from, with `telethon-cli config show`.
+
+### Proxy
+
+On networks where Telegram is throttled or blocked, route the client through a
+proxy with `TG_PROXY` (or the `--proxy` flag, or legacy `TELETHON_PROXY`):
+
+```dotenv
+TG_PROXY=socks5://user:pass@host:1080
+```
+
+Supported schemes: `socks5`, `socks4`, `http`. DNS resolves on the proxy side
+(`rdns=True`), which is what censored networks usually need. The proxy is used
+by every command that connects.
+
+The proxy support needs one extra dependency:
+
+```bash
+python -m pip install 'telethon-cli[proxy]'
+```
+
+Without it the CLI exits with an error instead of silently ignoring the proxy.
+
 On first login, `telethon-cli` can create and store a Telethon session in the
 project automatically. You can create it explicitly:
 
@@ -105,10 +148,12 @@ 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.
+automatically when present. The user config file participates in the same
+chain: CLI flags > environment/`.env` > user config > defaults. If the same
+Telethon setting is defined in several sources with different values, 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
+everything.
 
 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.
@@ -137,8 +182,57 @@ 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
+telethon-cli config show --output json
 ```
 
+## Schema Drift (temporary)
+
+Telethon releases lag the live Telegram TL schema. When a channel's history
+contains constructors the installed telethon does not know, iterating it fails
+with `TypeNotFoundError`. `telethon-cli schema` is an explicitly **temporary**
+bridge for that gap until upstream telethon ships a release covering the live
+schema.
+
+Check for drift — bundled layer vs a published schema, optionally with a
+read-only live probe of a channel (requires a logged-in session):
+
+```bash
+telethon-cli schema status --schema-file path/to/api.tl
+telethon-cli schema status --schema-file path/to/api.tl --probe @somechannel
+```
+
+`status` is read-only and needs no developer mode. It exits non-zero when the
+published layer cannot be determined, or when the probe hits unknown
+constructors (their ids are listed).
+
+Where to get a schema text: there is no public auto-updating source — the
+PyPI sdist stopped shipping `telethon_generator` data, and the upstream v1
+branch and docs pages lag the releases. Take `telethon_generator/data/api.tl`
+from the telethon source tree of the release you want to match (or any
+fresher TL schema text). `schema status --probe` is the ground truth when no
+fresher text exists.
+
+Patch the drift — generates deserialization-only classes for the constructors
+missing from the installed telethon and registers them in telethon's runtime
+lookup table. Gated behind developer mode; prints what it is about to do first:
+
+```bash
+telethon-cli schema patch --schema-file path/to/api.tl --dry-run
+telethon-cli schema patch --schema-file path/to/api.tl --yes
+telethon-cli schema patch --schema-file path/to/api.tl --probe @somechannel --yes
+```
+
+Notes:
+
+- The artifact is a single generated file, `.telethon-cli/tl_patch.py` at the
+  project root. It is applied automatically at startup for every subsequent
+  command in the project. Delete the file to undo.
+- Patched constructors are receive-only: sending them back is not supported.
+- Re-run `schema patch` after upgrading telethon (the override detects the
+  upgrade and disables itself).
+- Constructors newer than the newest obtainable schema cannot be synthesized;
+  the probe lists such ids as unpatchable.
+
 ## Release Process
 
 Build and validate release artifacts locally before uploading:
@@ -182,6 +276,21 @@ 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.
 
+### PyPI Token Scoping
+
+PyPI API tokens can be **account-wide** or **project-scoped**:
+
+- **Project-scoped** tokens only allow uploads to the specific project they were
+  created for. A token scoped to `telethon-cli` cannot upload `direct-cli` —
+  you will get **403 Forbidden**.
+- **Account-wide** tokens allow uploads to any project under your account.
+- For the **first publication** of a new project, you **must** use an
+  account-wide token (project-scoped tokens cannot be created until the project
+  exists on PyPI).
+- After the first successful upload, create a project-scoped token at
+  https://pypi.org/manage/account/token/ and replace the account-wide token in
+  `.env`.
+
 For every subsequent release, bump `version` in `pyproject.toml` before
 building. PyPI rejects uploads for versions that already exist.
 

telethon_cli-0.1.2/README.md

@@ -0,0 +1,283 @@
+# 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 `TG_API_ID` and `TG_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 TG_API_ID=...
+export TG_API_HASH=...
+```
+
+You can also keep them in a `.env` file in the current working directory or at
+the project root:
+
+```dotenv
+TG_API_ID=...
+TG_API_HASH=...
+```
+
+Legacy `TELETHON_API_ID`, `TELETHON_API_HASH`, `TELETHON_SESSION`, and
+`TELETHON_PASSWORD` are still accepted as compatibility aliases. When both
+namespaces are present, `telethon-cli` requires the values to match.
+
+### User config
+
+Settings that should persist across projects can live in an optional
+user-level config file at `~/.config/telethon-cli/config.json` (override the
+base directory with `XDG_CONFIG_HOME`):
+
+```json
+{
+  "api_id": 12345,
+  "api_hash": "...",
+  "session": "/path/to/session",
+  "proxy": "socks5://user:pass@host:1080"
+}
+```
+
+A missing file is not an error. Unknown keys are rejected so typos never pass
+silently, and secrets such as `api_hash` belong here or in the environment —
+never in committed files. Inspect the effective configuration, including where
+every value came from, with `telethon-cli config show`.
+
+### Proxy
+
+On networks where Telegram is throttled or blocked, route the client through a
+proxy with `TG_PROXY` (or the `--proxy` flag, or legacy `TELETHON_PROXY`):
+
+```dotenv
+TG_PROXY=socks5://user:pass@host:1080
+```
+
+Supported schemes: `socks5`, `socks4`, `http`. DNS resolves on the proxy side
+(`rdns=True`), which is what censored networks usually need. The proxy is used
+by every command that connects.
+
+The proxy support needs one extra dependency:
+
+```bash
+python -m pip install 'telethon-cli[proxy]'
+```
+
+Without it the CLI exits with an error instead of silently ignoring the proxy.
+
+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. The user config file participates in the same
+chain: CLI flags > environment/`.env` > user config > defaults. If the same
+Telethon setting is defined in several sources with different values, 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
+everything.
+
+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
+telethon-cli config show --output json
+```
+
+## Schema Drift (temporary)
+
+Telethon releases lag the live Telegram TL schema. When a channel's history
+contains constructors the installed telethon does not know, iterating it fails
+with `TypeNotFoundError`. `telethon-cli schema` is an explicitly **temporary**
+bridge for that gap until upstream telethon ships a release covering the live
+schema.
+
+Check for drift — bundled layer vs a published schema, optionally with a
+read-only live probe of a channel (requires a logged-in session):
+
+```bash
+telethon-cli schema status --schema-file path/to/api.tl
+telethon-cli schema status --schema-file path/to/api.tl --probe @somechannel
+```
+
+`status` is read-only and needs no developer mode. It exits non-zero when the
+published layer cannot be determined, or when the probe hits unknown
+constructors (their ids are listed).
+
+Where to get a schema text: there is no public auto-updating source — the
+PyPI sdist stopped shipping `telethon_generator` data, and the upstream v1
+branch and docs pages lag the releases. Take `telethon_generator/data/api.tl`
+from the telethon source tree of the release you want to match (or any
+fresher TL schema text). `schema status --probe` is the ground truth when no
+fresher text exists.
+
+Patch the drift — generates deserialization-only classes for the constructors
+missing from the installed telethon and registers them in telethon's runtime
+lookup table. Gated behind developer mode; prints what it is about to do first:
+
+```bash
+telethon-cli schema patch --schema-file path/to/api.tl --dry-run
+telethon-cli schema patch --schema-file path/to/api.tl --yes
+telethon-cli schema patch --schema-file path/to/api.tl --probe @somechannel --yes
+```
+
+Notes:
+
+- The artifact is a single generated file, `.telethon-cli/tl_patch.py` at the
+  project root. It is applied automatically at startup for every subsequent
+  command in the project. Delete the file to undo.
+- Patched constructors are receive-only: sending them back is not supported.
+- Re-run `schema patch` after upgrading telethon (the override detects the
+  upgrade and disables itself).
+- Constructors newer than the newest obtainable schema cannot be synthesized;
+  the probe lists such ids as unpatchable.
+
+## 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.
+
+### PyPI Token Scoping
+
+PyPI API tokens can be **account-wide** or **project-scoped**:
+
+- **Project-scoped** tokens only allow uploads to the specific project they were
+  created for. A token scoped to `telethon-cli` cannot upload `direct-cli` —
+  you will get **403 Forbidden**.
+- **Account-wide** tokens allow uploads to any project under your account.
+- For the **first publication** of a new project, you **must** use an
+  account-wide token (project-scoped tokens cannot be created until the project
+  exists on PyPI).
+- After the first successful upload, create a project-scoped token at
+  https://pypi.org/manage/account/token/ and replace the account-wide token in
+  `.env`.
+
+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
+```

telethon_cli-0.1.2/conftest.py

@@ -0,0 +1,36 @@
+"""Point test imports at the local src/ tree instead of the installed copy."""
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent / "src"))
+
+
+@pytest.fixture
+def project_root(tmp_path, monkeypatch):
+    """A throwaway project root (cwd + planted pyproject.toml)."""
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "pyproject.toml").write_text("", encoding="utf-8")
+    return tmp_path
+
+
+@pytest.fixture(autouse=True)
+def isolated_user_config(tmp_path, monkeypatch):
+    """Keeps os.environ-based flows away from the developer's real user config."""
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg-config"))
+
+
+def _write_user_config(tmp_path, payload):
+    config_dir = tmp_path / "xdg" / "telethon-cli"
+    config_dir.mkdir(parents=True)
+    path = config_dir / "config.json"
+    path.write_text(json.dumps(payload), encoding="utf-8")
+    return path
+
+
+def _user_config_environ(tmp_path, **extra):
+    environ = {"XDG_CONFIG_HOME": str(tmp_path / "xdg")}
+    environ.update(extra)
+    return environ

{telethon_cli-0.1.1 → telethon_cli-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "telethon-cli"
-version = "0.1.1"
+version = "0.1.2"
 description = "Command-line interface for Telethon and Telethon internals"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -32,6 +32,9 @@ dependencies = [
     "Telethon>=1"
 ]
 
+[project.optional-dependencies]
+proxy = ["python-socks[asyncio]>=2"]
+
 [project.urls]
 Homepage = "https://github.com/axisrow/telethon-cli"
 Repository = "https://github.com/axisrow/telethon-cli"