tgpost 0.1.0__py3-none-any.whl

tgpost/__init__.py

@@ -0,0 +1,38 @@
+"""tgpost - Send messages and files to Telegram channels, now or on a schedule
+
+Author: Pandiyaraj Karuppasamy
+Date: Sep-05-2026
+"""
+
+__version__ = "0.1.0"
+
+from .client import TelegramClient
+from .errors import (
+    AuthError,
+    BadRequestError,
+    ConfigError,
+    FileTooLargeError,
+    ForbiddenError,
+    NetworkError,
+    RateLimitError,
+    SchedulerError,
+    ServerError,
+    TelegramError,
+    TgPostError,
+)
+
+__all__ = [
+    "TelegramClient",
+    "TgPostError",
+    "ConfigError",
+    "TelegramError",
+    "AuthError",
+    "BadRequestError",
+    "ForbiddenError",
+    "RateLimitError",
+    "ServerError",
+    "NetworkError",
+    "FileTooLargeError",
+    "SchedulerError",
+    "__version__",
+]

tgpost/__main__.py

@@ -0,0 +1,12 @@
+"""Entry point so the package can be run as `python -m tgpost`.
+
+Author: Pandiyaraj Karuppasamy
+Date: Sep-05-2026
+"""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

tgpost/cli.py

@@ -0,0 +1,482 @@
+"""Command line interface.
+
+Author: Pandiyaraj Karuppasamy
+Date: Sep-05-2026
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .client import TelegramClient
+from .config import ENV_TOKEN, Config, Target, config_path, db_path, load_config, save_targets
+from .errors import TgPostError
+from .formatting import PARSE_MODES
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_USAGE = 2
+
+DISCLAIMER = (
+    "Provided AS IS, without warranty of any kind. Use entirely at your own risk. "
+    "You are responsible for what you publish, for verifying the target channel, and "
+    "for being authorised to post there. A scheduled job posts unattended: a wrong "
+    "schedule can publish to a real audience repeatedly. See LICENSE, which governs."
+)
+
+
+def _make_output_utf8_safe() -> None:
+    """Stop a Unicode character in output from crashing a legacy Windows console.
+
+    Printing an arrow or a check mark to a cp1252 console raises
+    UnicodeEncodeError after the send has already succeeded, turning a completed
+    job into a non-zero exit. This reconfigures the streams where possible and
+    never raises.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(encoding="utf-8", errors="replace")
+        except (ValueError, OSError, LookupError):
+            try:
+                reconfigure(errors="replace")
+            except (ValueError, OSError, LookupError):
+                pass
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser.
+
+    Returns:
+        The configured parser, with one subparser per command.
+    """
+    parser = argparse.ArgumentParser(
+        prog="tgpost",
+        description="Send messages and files to Telegram channels, now or on a schedule.",
+        epilog=DISCLAIMER,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"tgpost {__version__}")
+    parser.add_argument("--token", help=f"bot token; overrides {ENV_TOKEN} and the config file")
+    parser.add_argument("--config", type=Path, help="path to the config file")
+    parser.add_argument("--base-url", help="Bot API root, for a local Bot API server")
+    parser.add_argument("-v", "--verbose", action="store_true", help="log what is happening")
+    subparsers = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    def add_send_arguments(sub: argparse.ArgumentParser) -> None:
+        """Attach the arguments shared by send and schedule."""
+        target = sub.add_argument_group("target")
+        target.add_argument("--to", help="a named target from the config file")
+        target.add_argument("--chat-id", help="a @channelusername or numeric chat id")
+        content = sub.add_argument_group("content")
+        content.add_argument("--text", help="message text, or the caption when a file is sent")
+        content.add_argument("--stdin", action="store_true", help="read the text from standard input")
+        content.add_argument("--file", action="append", default=[], metavar="PATH", help="file to send; repeatable")
+        content.add_argument("--kind", default="document", help="document, photo, video, audio, animation or voice")
+        content.add_argument("--album", action="store_true", help="send several files as one album")
+        content.add_argument("--parse-mode", choices=PARSE_MODES, help="how to interpret markup; defaults to html")
+        content.add_argument("--escape", action="store_true", help="escape the text rather than treating it as markup")
+        content.add_argument("--silent", action="store_true", help="send without a notification")
+
+    send = subparsers.add_parser("send", help="send now", epilog=DISCLAIMER)
+    add_send_arguments(send)
+    send.add_argument("--dry-run", action="store_true", help="show what would be sent without sending")
+
+    schedule = subparsers.add_parser("schedule", help="send later, or repeatedly", epilog=DISCLAIMER)
+    add_send_arguments(schedule)
+    when = schedule.add_argument_group("when")
+    when.add_argument("--at", help="one-shot time: an ISO timestamp, or an offset such as 30m")
+    when.add_argument("--every", help="repeat interval, such as 15m, 2h or 1d")
+    when.add_argument("--cron", help="cron expression, such as '0 9 * * 1-5'")
+    when.add_argument("--tz", help="IANA time zone for --at and --cron, such as Europe/London")
+    schedule.add_argument("--name", help="a label for the job")
+
+    jobs = subparsers.add_parser("jobs", help="list scheduled jobs")
+    jobs.add_argument("--json", action="store_true", dest="as_json", help="output JSON")
+
+    cancel = subparsers.add_parser("cancel", help="cancel a scheduled job")
+    cancel.add_argument("job_id", help="the job id shown by tgpost jobs")
+
+    subparsers.add_parser("run-due", help="run every job that is due, then exit")
+    subparsers.add_parser("daemon", help="run jobs continuously until interrupted")
+
+    history = subparsers.add_parser("history", help="show recent job runs")
+    history.add_argument("--limit", type=int, default=20, help="how many runs to show")
+    history.add_argument("--job", help="restrict to one job id")
+
+    targets = subparsers.add_parser("targets", help="manage named channels")
+    target_commands = targets.add_subparsers(dest="targets_command", metavar="ACTION")
+    target_commands.add_parser("list", help="list configured targets")
+    add_target = target_commands.add_parser("add", help="add or update a target")
+    add_target.add_argument("name")
+    add_target.add_argument("chat_id", help="a @channelusername or numeric chat id")
+    add_target.add_argument("--description", default="", help="a note about this target")
+    add_target.add_argument("--parse-mode", choices=PARSE_MODES, help="parse mode for this target")
+    remove_target = target_commands.add_parser("remove", help="remove a target")
+    remove_target.add_argument("name")
+
+    subparsers.add_parser("check", help="verify the token and every target")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the command line interface.
+
+    Args:
+        argv: Arguments to parse. Defaults to sys.argv.
+
+    Returns:
+        A process exit code: 0 on success, 1 on a handled error, 2 on misuse.
+    """
+    _make_output_utf8_safe()
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if not args.command:
+        parser.print_help()
+        return EXIT_USAGE
+
+    logging.basicConfig(
+        level=logging.INFO if args.verbose else logging.WARNING,
+        format="%(levelname)s %(message)s",
+    )
+
+    try:
+        config = load_config(args.config, token_override=args.token)
+        if args.base_url:
+            config.base_url = args.base_url.rstrip("/")
+
+        handlers = {
+            "send": _command_send,
+            "schedule": _command_schedule,
+            "jobs": _command_jobs,
+            "cancel": _command_cancel,
+            "run-due": _command_run_due,
+            "daemon": _command_daemon,
+            "history": _command_history,
+            "targets": _command_targets,
+            "check": _command_check,
+        }
+        return handlers[args.command](args, config)
+    except TgPostError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    except FileNotFoundError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+    except KeyboardInterrupt:
+        print("interrupted", file=sys.stderr)
+        return EXIT_ERROR
+
+
+def _resolve_chat(args: argparse.Namespace, config: Config) -> tuple[str, str | None]:
+    """Work out which chat to post to.
+
+    Args:
+        args: Parsed arguments carrying --to or --chat-id.
+        config: Loaded configuration holding named targets.
+
+    Returns:
+        The chat id and any parse mode the target overrides.
+
+    Raises:
+        ValueError: If neither or both of --to and --chat-id were given.
+        ConfigError: If a named target does not exist.
+    """
+    if args.chat_id and args.to:
+        raise ValueError("give either --to or --chat-id, not both")
+    if args.chat_id:
+        return args.chat_id, None
+    if args.to:
+        target = config.resolve_target(args.to)
+        return target.chat_id, target.parse_mode
+    raise ValueError("no target given; use --to NAME or --chat-id ID")
+
+
+def _collect_text(args: argparse.Namespace) -> str | None:
+    """Return the message text from --text or standard input."""
+    if args.stdin:
+        return sys.stdin.read()
+    return args.text
+
+
+def _command_send(args: argparse.Namespace, config: Config) -> int:
+    """Send a message or files immediately."""
+    chat_id, target_mode = _resolve_chat(args, config)
+    text = _collect_text(args)
+    files = [Path(p) for p in args.file]
+    parse_mode = args.parse_mode or target_mode or config.parse_mode
+
+    if not text and not files:
+        raise ValueError("nothing to send; give --text, --stdin or --file")
+
+    if args.dry_run:
+        print(f"would send to {chat_id}")
+        if text:
+            preview = text if len(text) <= 200 else text[:200] + "..."
+            print(f"  text ({len(text)} chars, parse mode {parse_mode}): {preview}")
+        for path in files:
+            size = path.stat().st_size if path.is_file() else 0
+            marker = "" if path.is_file() else "  [missing]"
+            print(f"  file: {path} ({size} bytes){marker}")
+        return EXIT_OK
+
+    with TelegramClient(config.require_token(), base_url=config.base_url) as client:
+        if files and args.album and len(files) >= 2:
+            client.send_media_group(chat_id, files, kind=args.kind if args.kind != "document" else "photo",
+                                    caption=text, parse_mode=parse_mode, escape=args.escape,
+                                    disable_notification=args.silent)
+            print(f"sent album of {len(files)} files to {chat_id}")
+        elif files:
+            for index, path in enumerate(files):
+                client.send_file(chat_id, path, kind=args.kind,
+                                 caption=text if index == 0 else None,
+                                 parse_mode=parse_mode, escape=args.escape,
+                                 disable_notification=args.silent)
+                print(f"sent {path.name} to {chat_id}")
+        else:
+            # Reachable only with no files, and the guard above rejects the
+            # no-text-and-no-files case, so text is set here.
+            assert text is not None
+            parts = client.send_message(chat_id, text, parse_mode=parse_mode, escape=args.escape,
+                                        disable_notification=args.silent)
+            suffix = f" in {len(parts)} messages" if len(parts) > 1 else ""
+            print(f"sent to {chat_id}{suffix}")
+    return EXIT_OK
+
+
+def _command_schedule(args: argparse.Namespace, config: Config) -> int:
+    """Create a scheduled job."""
+    from .scheduler import Scheduler, new_job_id, parse_interval, parse_when
+    from .store import Job
+
+    chosen = [flag for flag in (args.at, args.every, args.cron) if flag]
+    if len(chosen) != 1:
+        raise ValueError("give exactly one of --at, --every or --cron")
+
+    chat_id, target_mode = _resolve_chat(args, config)
+    text = _collect_text(args)
+    files = [str(Path(p).resolve()) for p in args.file]
+    if not text and not files:
+        raise ValueError("nothing to schedule; give --text, --stdin or --file")
+
+    for path in files:
+        if not Path(path).is_file():
+            raise FileNotFoundError(f"no such file: {path}. A scheduled job reads the file when it fires, so the path must persist.")
+
+    if args.at:
+        kind = "date"
+        spec: dict[str, Any] = {"run_at": parse_when(args.at, args.tz).isoformat()}
+        summary = f"once at {spec['run_at']}"
+    elif args.every:
+        kind = "interval"
+        spec = {"seconds": parse_interval(args.every).total_seconds()}
+        summary = f"every {args.every}"
+    else:
+        kind = "cron"
+        spec = {"expression": args.cron}
+        summary = f"cron {args.cron}"
+
+    job = Job(
+        id=new_job_id(),
+        name=args.name or (f"send to {chat_id}"),
+        chat_id=chat_id,
+        payload={
+            "text": text,
+            "files": files,
+            "kind": args.kind,
+            "album": args.album,
+            "parse_mode": args.parse_mode or target_mode or config.parse_mode,
+            "escape": args.escape,
+            "silent": args.silent,
+        },
+        trigger_kind=kind,
+        trigger_spec=spec,
+        timezone=args.tz,
+    )
+
+    with Scheduler(config) as scheduler:
+        scheduler.add(job)
+
+    print(f"scheduled job {job.id}: {summary}")
+    print("run 'tgpost daemon' to keep it running, or 'tgpost run-due' from Task Scheduler or cron.")
+    return EXIT_OK
+
+
+def _command_jobs(args: argparse.Namespace, config: Config) -> int:
+    """List scheduled jobs."""
+    from .scheduler import Scheduler, describe_trigger
+
+    with Scheduler(config) as scheduler:
+        jobs = scheduler.list_jobs()
+        next_times = scheduler.next_run_times() if jobs else {}
+
+    if args.as_json:
+        rows = []
+        for job in jobs:
+            next_run = next_times.get(job.id)
+            rows.append({
+                "id": job.id,
+                "name": job.name,
+                "chat_id": job.chat_id,
+                "trigger": describe_trigger(job),
+                "next_run": next_run.isoformat() if next_run else None,
+            })
+        print(json.dumps(rows, indent=2))
+        return EXIT_OK
+
+    if not jobs:
+        print("no scheduled jobs. Create one with: tgpost schedule --to NAME --text ... --cron '0 9 * * 1-5'")
+        return EXIT_OK
+
+    print(f"{'ID':<10} {'NEXT RUN':<26} {'TRIGGER':<28} NAME")
+    for job in jobs:
+        next_run = next_times.get(job.id)
+        when = next_run.strftime("%Y-%m-%d %H:%M:%S %Z") if next_run else "not scheduled"
+        print(f"{job.id:<10} {when:<26} {describe_trigger(job):<28} {job.name}")
+    return EXIT_OK
+
+
+def _command_cancel(args: argparse.Namespace, config: Config) -> int:
+    """Cancel a scheduled job."""
+    from .scheduler import Scheduler
+
+    with Scheduler(config) as scheduler:
+        if scheduler.cancel(args.job_id):
+            print(f"cancelled job {args.job_id}")
+            return EXIT_OK
+    print(f"no job with id {args.job_id}", file=sys.stderr)
+    return EXIT_ERROR
+
+
+def _command_run_due(args: argparse.Namespace, config: Config) -> int:
+    """Run every due job, then exit."""
+    from .scheduler import Scheduler
+
+    with Scheduler(config) as scheduler:
+        fired = scheduler.run_due()
+    print(f"ran {fired} job{'s' if fired != 1 else ''}")
+    return EXIT_OK
+
+
+def _command_daemon(args: argparse.Namespace, config: Config) -> int:
+    """Run jobs continuously until interrupted."""
+    from .scheduler import Scheduler
+
+    with Scheduler(config) as scheduler:
+        print(f"running scheduled jobs from {scheduler.database}. Press Ctrl+C to stop.")
+        scheduler.run_daemon()
+    return EXIT_OK
+
+
+def _command_history(args: argparse.Namespace, config: Config) -> int:
+    """Show recent job runs."""
+    from .store import JobStore
+
+    with JobStore(db_path()) as store:
+        runs = store.list_history(limit=args.limit, job_id=args.job)
+
+    if not runs:
+        print("no runs recorded yet")
+        return EXIT_OK
+
+    print(f"{'FIRED AT':<28} {'JOB':<10} {'OUTCOME':<9} DETAIL")
+    for run in runs:
+        print(f"{run['fired_at']:<28} {run['job_id']:<10} {run['outcome']:<9} {run['detail'] or ''}")
+    return EXIT_OK
+
+
+def _command_targets(args: argparse.Namespace, config: Config) -> int:
+    """List, add or remove named targets."""
+    action = args.targets_command or "list"
+
+    if action == "list":
+        if not config.targets:
+            print(f"no targets configured in {config.path or config_path()}")
+            print("add one with: tgpost targets add release-notes -1001234567890")
+            return EXIT_OK
+        print(f"{'NAME':<20} {'CHAT ID':<22} DESCRIPTION")
+        for name in sorted(config.targets):
+            target = config.targets[name]
+            print(f"{name:<20} {target.chat_id:<22} {target.description}")
+        return EXIT_OK
+
+    if action == "add":
+        config.targets[args.name] = Target(
+            name=args.name,
+            chat_id=args.chat_id,
+            parse_mode=args.parse_mode,
+            description=args.description,
+        )
+        written = save_targets(config, args.config)
+        print(f"added target {args.name} -> {args.chat_id} in {written}")
+        return EXIT_OK
+
+    if action == "remove":
+        if args.name not in config.targets:
+            print(f"no target named {args.name}", file=sys.stderr)
+            return EXIT_ERROR
+        del config.targets[args.name]
+        written = save_targets(config, args.config)
+        print(f"removed target {args.name} from {written}")
+        return EXIT_OK
+
+    raise ValueError(f"unknown targets action {action!r}")
+
+
+def _command_check(args: argparse.Namespace, config: Config) -> int:
+    """Verify the token and every configured target.
+
+    The two failures that waste the most time are a bot that is not a channel
+    administrator and one lacking can_post_messages, so both are reported
+    explicitly rather than surfacing later as a 403 on a real send.
+    """
+    failures = 0
+    with TelegramClient(config.require_token(), base_url=config.base_url) as client:
+        me = client.get_me()
+        bot_id = me["id"]
+        print(f"token OK: @{me.get('username')} (id {bot_id})")
+
+        if not config.targets:
+            print("no targets configured; nothing else to check")
+            return EXIT_OK
+
+        for name in sorted(config.targets):
+            target = config.targets[name]
+            try:
+                chat = client.get_chat(target.chat_id)
+                member = client.get_chat_member(target.chat_id, bot_id)
+                status = member.get("status")
+                title = chat.get("title") or chat.get("username") or target.chat_id
+                if chat.get("type") == "channel" and not member.get("can_post_messages"):
+                    print(f"  {name}: FAIL - bot is {status} in {title} but cannot post messages")
+                    failures += 1
+                elif status not in ("administrator", "creator", "member"):
+                    print(f"  {name}: FAIL - bot is {status} in {title}")
+                    failures += 1
+                else:
+                    print(f"  {name}: OK - can post to {title} (id {chat.get('id')})")
+            except TgPostError as exc:
+                print(f"  {name}: FAIL - {exc}")
+                failures += 1
+
+    if failures:
+        print(f"\n{failures} target(s) not ready. Add the bot as an administrator with permission to post.", file=sys.stderr)
+        return EXIT_ERROR
+    return EXIT_OK
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())