semvec/pypi-packages huggingface dataset:
tgsession 0.1.0
Telegram Session Toolkit (Telethon & Pyrogram)
License: MIT
Requires Python: >=3.9

# tgsession

**Telegram Session Toolkit**
Generate, inspect, dump, and convert Telegram sessions between **Telethon** and **Pyrogram**.

`tgsession` is designed to be **clean, explicit, and predictable** — no magic, no broken conversions, no messy side effects.

---

## ✨ Features

* Generate **Telethon** sessions
* Generate **Pyrogram** sessions
* Convert sessions:

  * Telethon → Pyrogram (string)
  * Pyrogram → Telethon (planned)
* Inspect Telethon `.session` files
* Dump Telethon session metadata as JSON
* Clean, colored CLI output (Colorama)
* Works on **Linux / Termux / GitHub Actions**

> ⚠️ File-based Pyrogram session conversion is experimental. String sessions are the recommended and stable format.

---

## 📦 Installation

```bash
git clone https://github.com/ankit-chaubey/tgsession.git
cd tgsession
pip install -e .
```

Or from PyPI release:

```bash
pip install tgsession
```

---

## 🚀 Usage

### General Help

```bash
tgsession --help
```

---

## 🔧 Generate Sessions

### Generate a Telethon session

```bash
tgsession gen tl myaccount
```

Creates:

* `myaccount.session` (Telethon SQLite session)

---

### Generate a Pyrogram session

```bash
tgsession gen pyro myaccount
```

Creates:

* Pyrogram **string session** (recommended)

---

## 🔍 Inspect Sessions

### Inspect a Telethon session

```bash
tgsession inspect myaccount.session
```

Shows:

* DC ID
* Server address
* Port

---

## 📤 Dump Sessions

### Dump Telethon session as JSON

```bash
tgsession dump myaccount.session
```

Outputs structured metadata useful for debugging and tooling.

---

## 🔄 Convert Sessions

### Telethon → Pyrogram (string session)

```bash
tgsession convert tl myaccount.session pyro
```

Output:

* Pyrogram **string session** (printed to stdout)

---

## 🧠 Design Philosophy

* **Explicit > Implicit**
* No hidden authorization steps
* No silent session mutation
* One clear source of truth per session

If something converts — it *really* converts.

---

## 🗂 Project Structure

```
tgsession/
├── cli.py                 # CLI entry point
├── gen/
│   ├── telethon_gen.py    # Telethon generator
│   └── pyrogram_gen.py    # Pyrogram generator
├── inspect/
│   └── telethon_inspect.py
├── dump/
│   └── telethon_dump.py
├── convert/
│   ├── tl_to_pyro.py
│   └── pyro_to_tl.py
└── core/
    └── utils.py
```

---

## 🛣 Roadmap

* [ ] Stable Pyrogram → Telethon conversion
* [ ] Optional Pyrogram file session export
* [ ] Non-interactive mode (CI friendly)
* [ ] Plugin system

---

## 👤 Author

**Ankit Chaubey**
GitHub: [https://github.com/ankit-chaubey](https://github.com/ankit-chaubey)

---

## 📄 License

MIT License