tdelegram 0.1.0__tar.gz

tdelegram-0.1.0/.env.example

@@ -0,0 +1,8 @@
+# Copy to .env or export directly. Never commit real secrets.
+TELEGRAM_API_ID=
+TELEGRAM_API_HASH=
+TELEGRAM_PHONE=
+# Optional:
+TELEGRAM_DB_KEY=
+TDELEGRAM_TDJSON=
+TDELEGRAM_HOME=

tdelegram-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,96 @@
+name: Bug report
+description: Something behaves differently than documented
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Before you paste anything:** TDelegram talks to a real Telegram
+        account. Never include your `api_hash`, your session directory
+        (`~/.tdelegram/`), a database key, or an unredacted log. Replace chat
+        titles, phone numbers and message text if they are not yours to share.
+
+        Found a security problem? Do not open an issue — see
+        [SECURITY.md](../blob/main/SECURITY.md).
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you expected, and what you got instead.
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Command or code
+      description: The smallest command or snippet that shows the problem.
+      render: shell
+      placeholder: tdelegram chat history --chat somechat --limit 5
+    validations:
+      required: true
+
+  - type: textarea
+    id: output
+    attributes:
+      label: Output
+      description: >
+        Data goes to stdout, diagnostics to stderr, so capture both.
+        Re-run with `--verbose` if it is not obvious. Redact before pasting.
+      render: shell
+    validations:
+      required: false
+
+  - type: input
+    id: tdelegram-version
+    attributes:
+      label: TDelegram version
+      placeholder: "0.1.0, or a commit sha"
+    validations:
+      required: true
+
+  - type: input
+    id: tdlib-version
+    attributes:
+      label: TDLib version
+      description: >
+        Many issues are really TDLib version differences. Your authorized
+        session reports it, or check your install.
+      placeholder: "1.8.67"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install
+    attributes:
+      label: How is libtdjson installed?
+      options:
+        - Homebrew (macOS)
+        - Built from source
+        - Docker image from this repo
+        - Distribution package
+        - Other / not sure
+    validations:
+      required: true
+
+  - type: input
+    id: platform
+    attributes:
+      label: OS and Python version
+      placeholder: "macOS 15.6 / Python 3.12.4"
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: gate
+    attributes:
+      label: Does this involve the write gate?
+      description: >
+        A method classified read/write/destructive in `methods.json`. A wrong
+        verdict is a safety bug and gets priority.
+      options:
+        - label: A mutating call went through without `--yes`
+        - label: A read-only call was refused as a write
+        - label: The verdict for a method looks wrong
+        - label: Not related to the gate

tdelegram-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/bulanovdm/TDelegram/security/advisories/new
+    about: Report privately. Never open a public issue for a security problem.

tdelegram-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,38 @@
+name: Feature request
+description: Suggest a capability or an ergonomics change
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What are you trying to do?
+      description: The task, not the solution. What are you working around today?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What would you like instead?
+    validations:
+      required: true
+
+  - type: input
+    id: tdlib-method
+    attributes:
+      label: Relevant TDLib method, if you know it
+      description: >
+        All 1022 are already reachable via `tdelegram call --request`, so this
+        is usually about ergonomics rather than coverage. Naming the method
+        helps either way.
+      placeholder: "getChatSponsoredMessages"
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: mutating
+    attributes:
+      label: Does it mutate anything?
+      options:
+        - label: Yes, it writes or deletes (it will need the confirmation gate)
+        - label: No, it is read-only

tdelegram-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+## What this changes
+
+<!-- And why. Link an issue if there is one. -->
+
+## Checklist
+
+- [ ] `pytest` passes (no account, no network, no TDLib required)
+- [ ] `ruff check src tests scripts` and `mypy --strict src/` are clean
+- [ ] Mutating behaviour has a test proving the gate previews without `--yes`
+- [ ] `methods.json` was regenerated, not hand-edited, if the schema changed
+- [ ] No session data, `api_hash`, or real message content in the diff or tests

tdelegram-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+  workflow_call: # reused as the release gate
+
+env:
+  # TDLib generates td_api.h at build time, so CI reads the scheme file it is
+  # generated from instead of building TDLib (~20 min). Both parse to the same
+  # function set. Bump this together with methods.json and the expected count
+  # in tests/contract/test_registry.py.
+  TDLIB_COMMIT: d1085f9cebc5a62379991ae1652673954f229c1f
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # The floor and the ceiling of what pyproject claims to support.
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+
+      - name: Fetch pinned TDLib scheme
+        run: |
+          curl -fsSL -o "$RUNNER_TEMP/td_api.tl" \
+            "https://raw.githubusercontent.com/tdlib/td/$TDLIB_COMMIT/td/generate/scheme/td_api.tl"
+          echo "TDELEGRAM_TD_API=$RUNNER_TEMP/td_api.tl" >> "$GITHUB_ENV"
+
+      - name: Registry and request shapes are in sync with the schema
+        run: |
+          python scripts/generate_method_registry.py --output src/tdelegram/methods.json
+          git diff --exit-code -- src/tdelegram/methods.json src/tdelegram/schema.json
+
+      - run: pytest -q
+      - run: ruff check src tests scripts
+      - run: mypy --strict src/

tdelegram-0.1.0/.github/workflows/docker.yml

@@ -0,0 +1,195 @@
+name: docker
+
+# Publishes ghcr.io/bulanovdm/tdelegram so the documented install is a pull
+# rather than a 20-minute TDLib compile on the user's machine. That is the only
+# thing that makes Docker a reasonable default.
+#
+# Tags, and what moves them (RELEASING.md has the whole scheme):
+#
+#   push to main            main, sha-<commit>
+#   release v1.2.3          1.2.3, and 1.2, 1 and latest where it is the newest
+#   pre-release v1.3.0rc1   1.3.0rc1
+#
+# `latest` is the newest release, never main. Release images come only from
+# release.yml, which calls this workflow once the suite has passed and the tag
+# agrees with pyproject.toml, with the tags scripts/release.py chose: which
+# floating tags a release takes depends on every other release, and that is
+# decided, and tested, in one place.
+
+on:
+  push:
+    branches: [main]
+  workflow_call:
+    inputs:
+      version:
+        description: The version being released, which the image must report
+        type: string
+        required: true
+      tags:
+        description: Every tag the release takes, separated by spaces
+        type: string
+        required: true
+  # Rebuilds a branch. A release's image is never rebuilt in place, not even
+  # for a base image fix: that is a patch release (RELEASING.md).
+  workflow_dispatch:
+
+env:
+  REGISTRY: ghcr.io
+
+jobs:
+  # Decided once, so the per-arch images and the manifest list cannot disagree
+  # about which build they are.
+  meta:
+    runs-on: ubuntu-latest
+    permissions: {}
+    outputs:
+      image: ${{ steps.meta.outputs.image }}
+      tags: ${{ steps.meta.outputs.tags }}
+      version: ${{ steps.meta.outputs.version }}
+    steps:
+      - id: meta
+        env:
+          RELEASE_VERSION: ${{ inputs.version }}
+          RELEASE_TAGS: ${{ inputs.tags }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          # A ghcr.io repository must be lowercase, but github.repository keeps
+          # the repo's own capitalisation (bulanovdm/TDelegram), which buildx
+          # rejects as an invalid reference.
+          echo "image=${REGISTRY}/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT"
+          if [[ -n "$RELEASE_VERSION" ]]; then
+            version="$RELEASE_VERSION"
+            tags="$RELEASE_TAGS"
+          elif [[ "$GITHUB_REF" == refs/heads/* ]]; then
+            # A branch name becomes a tag once what a tag cannot hold is a dash.
+            version="$(printf '%s' "$GITHUB_REF_NAME" | tr -c 'A-Za-z0-9_.-' '-')"
+            version="${version:0:128}"
+            tags="$version"
+            if [[ "$GITHUB_REF_NAME" == "$DEFAULT_BRANCH" ]]; then
+              tags+=" sha-${GITHUB_SHA::7}"
+            fi
+          else
+            echo "::error::Release images are published by release.yml. Run this on a branch." >&2
+            exit 1
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "tags=$tags" >> "$GITHUB_OUTPUT"
+
+  # Built on native runners per architecture. TDLib under QEMU emulation takes
+  # hours, and Apple Silicon needs arm64, so neither arch can simply be dropped.
+  build:
+    needs: meta
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux/amd64
+            runner: ubuntu-latest
+          - platform: linux/arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+    permissions:
+      contents: read
+      packages: write
+    env:
+      IMAGE: ${{ needs.meta.outputs.image }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push by digest
+        id: build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: ${{ matrix.platform }}
+          # What `docker inspect` answers when asked which build an image is.
+          labels: |
+            org.opencontainers.image.version=${{ needs.meta.outputs.version }}
+            org.opencontainers.image.revision=${{ github.sha }}
+          outputs: type=image,name=${{ env.IMAGE }},push-by-digest=true,name-canonical=true,push=true
+          cache-from: type=gha,scope=${{ matrix.platform }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.platform }}
+
+      # Each architecture runs by digest, on its own runner, before anything
+      # is tagged: a broken image never becomes `latest`, and arm64 is tried
+      # natively rather than not at all.
+      - name: Smoke-test the image
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+          RELEASE_VERSION: ${{ inputs.version }}
+        run: |
+          reported="$(docker run --rm "$IMAGE@$DIGEST" version)"
+          echo "tdelegram version: $reported"
+          if [[ -n "$RELEASE_VERSION" && "$reported" != "$RELEASE_VERSION" ]]; then
+            echo "::error::The image reports $reported but would be tagged $RELEASE_VERSION." >&2
+            exit 1
+          fi
+          # The registry must ship inside the image: the write gate fails closed
+          # without it, so an image missing methods.json refuses every call.
+          docker run --rm --entrypoint python "$IMAGE@$DIGEST" \
+            -c "from tdelegram import safety; assert safety.verdict('sendMessage') == 'write'; print('gate ok')"
+
+      - name: Export the digest
+        # The filename is the bare hex: upload-artifact rejects a colon, so the
+        # "sha256:" prefix cannot stay. The manifest job puts it back.
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+        run: |
+          mkdir -p /tmp/digests
+          touch "/tmp/digests/${DIGEST#sha256:}"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: digest-${{ strategy.job-index }}
+          path: /tmp/digests/*
+          retention-days: 1
+
+  # One multi-arch manifest list per tag, each pointing at both per-arch images.
+  manifest:
+    needs: [meta, build]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    env:
+      IMAGE: ${{ needs.meta.outputs.image }}
+      IMAGE_TAGS: ${{ needs.meta.outputs.tags }}
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: /tmp/digests
+          pattern: digest-*
+          merge-multiple: true
+
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Tag both images
+        working-directory: /tmp/digests
+        run: |
+          read -ra tags <<< "$IMAGE_TAGS"
+          args=()
+          for tag in "${tags[@]}"; do args+=(-t "$IMAGE:$tag"); done
+          for digest in *; do args+=("$IMAGE@sha256:$digest"); done
+          docker buildx imagetools create "${args[@]}"
+          {
+            echo "### Published"
+            for tag in "${tags[@]}"; do echo "- \`$IMAGE:$tag\`"; done
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Show the published manifest list
+        env:
+          VERSION: ${{ needs.meta.outputs.version }}
+        run: docker buildx imagetools inspect "$IMAGE:$VERSION"

tdelegram-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,155 @@
+name: release
+
+# A version tag is a release:
+#   git tag v0.2.0 && git push origin v0.2.0
+#
+# Nothing is published until the suite passes on every supported interpreter
+# and the tag, pyproject.toml and CHANGELOG.md agree on the version. Then, one
+# after another, so that a failure stops everything after it: the wheel is
+# built and tried, the Docker image is built, tried and tagged, PyPI gets the
+# sdist and the wheel, and a GitHub release carries both files with the
+# version's CHANGELOG.md section as its notes. PyPI never accepts a version
+# twice, so it comes after everything that can still fail. RELEASING.md says
+# what to do when a step does.
+#
+# PyPI authentication is Trusted Publishing (OIDC). There is no API token
+# anywhere: no repository secret to leak, rotate, or scope wrongly. The
+# one-time setup is on PyPI, not here -- see RELEASING.md.
+
+on:
+  push:
+    tags: ["v[0-9]*"]
+
+permissions:
+  contents: read
+
+jobs:
+  # Never publish something the suite has not passed on every supported
+  # interpreter. A tag is not a reason to skip the gate.
+  verify:
+    uses: ./.github/workflows/ci.yml
+
+  # The tag must be "v" plus pyproject.toml's version, and CHANGELOG.md must
+  # have a dated section for it. Also decides, from every other release, which
+  # floating image tags this one takes and whether GitHub calls it "Latest".
+  check:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.release.outputs.version }}
+      prerelease: ${{ steps.release.outputs.prerelease }}
+      latest: ${{ steps.release.outputs.latest }}
+      docker_tags: ${{ steps.release.outputs.docker_tags }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # every tag, to tell whether a newer release exists
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install packaging
+
+      - id: release
+        run: |
+          python scripts/release.py "$GITHUB_REF_NAME" \
+            --tags "$(git tag --list 'v*')" \
+            --image "ghcr.io/${GITHUB_REPOSITORY,,}" \
+            --notes "$RUNNER_TEMP/notes.md" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: notes
+          path: ${{ runner.temp }}/notes.md
+
+  build:
+    needs: [verify, check]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+
+      - name: Install the wheel somewhere clean and run it
+        env:
+          VERSION: ${{ needs.check.outputs.version }}
+        run: |
+          python -m venv "$RUNNER_TEMP/relcheck"
+          "$RUNNER_TEMP/relcheck/bin/pip" install "dist/tdelegram-$VERSION-py3-none-any.whl"
+          reported="$("$RUNNER_TEMP/relcheck/bin/tdelegram" version)"
+          if [ "$reported" != "$VERSION" ]; then
+            echo "::error::the wheel reports $reported, not $VERSION" >&2
+            exit 1
+          fi
+          # methods.json must ship in the wheel: the write gate fails closed
+          # without it, so a wheel missing it refuses every call.
+          "$RUNNER_TEMP/relcheck/bin/python" -c \
+            "from tdelegram import safety; assert safety.verdict('sendMessage') == 'write'; print('gate ok')"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # Builds and tries the image on both architectures, then tags it. After the
+  # wheel, so a failure anywhere before this point leaves nothing published.
+  docker:
+    needs: [verify, check, build]
+    uses: ./.github/workflows/docker.yml
+    permissions:
+      contents: read
+      packages: write
+    with:
+      version: ${{ needs.check.outputs.version }}
+      tags: ${{ needs.check.outputs.docker_tags }}
+
+  pypi:
+    needs: [build, docker]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # the OIDC token that stands in for an API token
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  # Last, so the release page never lists something that is not out yet.
+  github-release:
+    needs: [check, pypi]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: actions/download-artifact@v4
+        with:
+          name: notes
+
+      - name: Publish the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          VERSION: ${{ needs.check.outputs.version }}
+          PRERELEASE: ${{ needs.check.outputs.prerelease }}
+          LATEST: ${{ needs.check.outputs.latest }}
+        run: |
+          if gh release view "$GITHUB_REF_NAME" > /dev/null 2>&1; then
+            # A re-run after the release was made: only make sure the files are on it.
+            gh release upload "$GITHUB_REF_NAME" dist/* --clobber
+          else
+            gh release create "$GITHUB_REF_NAME" dist/* \
+              --verify-tag \
+              --title "TDelegram $VERSION" \
+              --notes-file notes.md \
+              --prerelease="$PRERELEASE" \
+              --latest="$LATEST"
+          fi