From b1be5c2e63bb0f3b5d310d96408bad3fa10b8577 Mon Sep 17 00:00:00 2001 From: Pouri Date: Thu, 10 Sep 2026 23:57:56 +0330 Subject: [PATCH] release: publish as tlgr-cli, because PyPI will not take tlgr (2.0.1) PyPI refuses the name `tlgr`: "This project name is too similar to an existing project". The project it means is `tlgrm`, first published 2026-06-14, one letter away and describing itself as a command-line client and webhook daemon for Telegram built on Telethon. tlgr's own 1.0.0 is tagged 2026-03-06, so the name here is not shadowing anything, but the similarity check does not weigh dates and there is no reason to wait on an appeal to have a working install line. The distribution name is the only thing that moves. It is not the import name and not the command: nothing in the source reads it, `[project.scripts]` is keyed on `tlgr.cli:cli`, and `[tool.setuptools.package-data]` is keyed on the package. So `import tlgr` still works, `tlgr --version` still works, every module path is untouched, and the wheel installs the same 951 commands it did yesterday. What changes is `pip install tlgr` becoming `pip install tlgr-cli`. The version goes to 2.0.1 rather than re-tagging 2.0.0, because 2.0.0 is released and its artefacts are named `tlgr-2.0.0`. A distribution cannot be renamed under a version that already exists; the wheel PyPI serves has to be the wheel the release page carries. The install docs are corrected in the same commit rather than after it. They said tlgr was not on PyPI, which was true when it was written this morning and stops being true with this release, and README's `pip install tlgr` was wrong for the whole of 1.x. docs/UPGRADING.md now also says plainly that `pipx upgrade tlgr` does not work for a v1 install, and to uninstall the old one only after the new one answers `--version`: both provide the same `tlgr` command and must not sit side by side. --- CHANGELOG.md | 20 ++++++++++++++++++++ CONTRIBUTING.md | 9 +++++++-- README.md | 17 ++++++++++------- docs/UPGRADING.md | 30 ++++++++++++++++++------------ pyproject.toml | 5 ++++- tlgr/__init__.py | 2 +- 6 files changed, 60 insertions(+), 23 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6c7e17d..8039b57 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,26 @@ All notable changes to tlgr are recorded here. The format follows semantic versioning at the CLI surface, which means the JSON shapes and exit codes documented in `AGENT.md` are the public API. +## [2.0.1] — 2026-09-10 + +### Changed + +- **The distribution is published as `tlgr-cli`.** PyPI refuses the name + `tlgr` as too similar to an existing `tlgrm`, so the name on the index is + `tlgr-cli`. Nothing else moves: the import package is still `tlgr`, the + command is still `tlgr`, and every module path is unchanged. Only the + install line differs. + + ```bash + pipx install tlgr-cli # was: pipx install git+https://github.com/tlgrcli/tlgr.git + ``` + + If you already run tlgr from a git or editable install, you do not need to + do anything. Do not `pipx install tlgr-cli` alongside an existing `tlgr` + pipx install: both provide the same `tlgr` command and the second one will + collide with the first. `pipx uninstall tlgr` first, or keep the install + you have. + ## [2.0.0] — 2026-09-10 **Every command tlgr has is generated from the operation registry.** There is diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b5bd3ce..4a5c0f6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -115,11 +115,16 @@ workflow's OIDC token instead of an API token, so there is no publishing secret in this repository and nothing to leak or rotate. It has to be configured once, on pypi.org, before the first release that uses it: -- owner `tlgrcli`, repository `tlgr`, workflow `release.yml`, environment - `pypi`; +- PyPI project `tlgr-cli`, owner `tlgrcli`, repository `tlgr`, workflow + `release.yml`, environment `pypi`; - for the first release, add it as a *pending* publisher, since the project does not exist on PyPI until something is published to it. +The distribution is `tlgr-cli` rather than `tlgr` because PyPI rejects the +shorter name as too similar to an unrelated `tlgrm`. It is only the name on +the index: the import package and the console script are both `tlgr`, and +nothing in the source refers to the distribution name. + Until that publisher exists the `publish` job fails and the GitHub release still succeeds, which is the intended order: the release is the artefact of record, PyPI is a distribution channel on top of it. diff --git a/README.md b/README.md index 6bd16a2..eb640c7 100644 --- a/README.md +++ b/README.md @@ -6,15 +6,18 @@ Full Telegram account control from the terminal. Agent-friendly, daemon-based, with webhook event push. ``` -pipx install git+https://github.com/tlgrcli/tlgr.git +pipx install tlgr-cli ``` -tlgr is not published on PyPI, so `pip install tlgr` does not reach this -project. Install from the repository, or from the wheel attached to a -[release](https://github.com/tlgrcli/tlgr/releases). `pipx` is the -recommendation because tlgr runs a long-lived daemon and wants its own -environment; `pip install git+https://github.com/tlgrcli/tlgr.git` into a -virtualenv works the same way. +The command is `tlgr`; the distribution on PyPI is `tlgr-cli`, because the +shorter name was taken by an unrelated project. `pipx` is the recommendation +because tlgr runs a long-lived daemon and wants its own environment; +`pip install tlgr-cli` into a virtualenv works the same way. To track the +development tip instead, install from the repository: + +``` +pipx install git+https://github.com/tlgrcli/tlgr.git +``` > **For agents:** logging in is a sequence of ordinary commands — `tlgr auth send-code` then `tlgr auth verify-code` — so only *reading the code* needs a person. Secrets come from `--x-env`/`--x-stdin`/`--x-file`, never argv. See [AGENT.md](AGENT.md) for the full agent reference. diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md index abf32b2..3f9464d 100644 --- a/docs/UPGRADING.md +++ b/docs/UPGRADING.md @@ -78,18 +78,24 @@ removed on the next start — but an *open file handle* is not. ## 2. Upgrade the install ```bash -pipx install --force git+https://github.com/tlgrcli/tlgr.git -tlgr --version # expect 2.0.0 +pipx install tlgr-cli +tlgr --version # expect 2.0.1 or later ``` -tlgr is not on PyPI, so `pipx upgrade tlgr` and `pip install -U tlgr` have -nothing to upgrade from: the install came from this repository and so does -the upgrade. `--force` because pipx will not reinstall over an existing -install otherwise. Into a virtualenv it is -`pip install -U 'tlgr @ git+https://github.com/tlgrcli/tlgr.git'`, and the -wheel attached to the [2.0.0 -release](https://github.com/tlgrcli/tlgr/releases/tag/v2.0.0) installs the -same build without git. +The distribution is named `tlgr-cli` on PyPI; the command it installs is +`tlgr`. **`pipx upgrade tlgr` does not work**, and neither does +`pip install -U tlgr`: a v1 install came from this repository, not from an +index, so there is no `tlgr` distribution for pipx to upgrade. Install the +new name, then remove the old install once you have checked it works: + +```bash +pipx uninstall tlgr # only after `tlgr --version` reports the new build +``` + +Both provide the same `tlgr` command, so do not leave the two installed +side by side. Into a virtualenv it is `pip install -U tlgr-cli`, and the +wheel attached to any [release](https://github.com/tlgrcli/tlgr/releases) +installs the same build without an index. ### A pipx editable install — the checkout *is* the install @@ -108,7 +114,7 @@ With the daemon stopped, move the checkout: git -C fetch git -C checkout main # or, on the deployed branch: git -C merge --ff-only origin/main -tlgr --version # expect 2.0.0 +tlgr --version # expect 2.0.1 or later ``` `--ff-only` on purpose: a merge commit in a deployment checkout is a local @@ -132,7 +138,7 @@ extra set rather than adding to it. Then check the imports resolve before starting anything: ```bash -tlgr --version # expect 2.0.0 +tlgr --version # expect 2.0.1 or later tlgr agent whoami --json # imports msgspec and Telethon; fails loudly if either is missing ``` diff --git a/pyproject.toml b/pyproject.toml index 28a7a2b..324efb5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,7 +3,10 @@ requires = ["setuptools>=61.0", "wheel"] build-backend = "setuptools.build_meta" [project] -name = "tlgr" +# The distribution name, which is not the import name and not the command. +# PyPI refuses "tlgr" as too similar to an existing "tlgrm"; the module stays +# `tlgr`, the console script stays `tlgr`, and only `pip install` differs. +name = "tlgr-cli" dynamic = ["version"] description = "Full Telegram account control CLI — agent-friendly, daemon-based, with webhook event push" readme = "README.md" diff --git a/tlgr/__init__.py b/tlgr/__init__.py index 23cba85..4ecd4ce 100644 --- a/tlgr/__init__.py +++ b/tlgr/__init__.py @@ -1,3 +1,3 @@ """tlgr — Full Telegram account control CLI.""" -__version__ = "2.0.0" +__version__ = "2.0.1"