Metadata-Version: 2.4
Name: tdata-reader
Version: 0.1.0
Summary: Read Telegram Desktop tdata folders into Telethon-ready accounts.
Author: Aleksey Kravtsun
License: MIT
Project-URL: Homepage, https://github.com/kr-aleksey/tdata_reader
Project-URL: Repository, https://github.com/kr-aleksey/tdata_reader
Project-URL: Issues, https://github.com/kr-aleksey/tdata_reader/issues
Keywords: telegram,tdata,tdesktop,telethon,session
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: telethon>=1.30
Dynamic: license-file

# tdata_reader

Read Telegram Desktop's `tdata` folder and extract everything needed to
spin up a Telethon client — without PyQt5 and without any native crypto
extension.

The library is a stripped-down, dependency-light fork of the data-reading
parts of [opentele](https://github.com/thedemons/opentele): it only does
the **read-tdata → Telethon-session** direction, which is the common use
case in account-management tools.

## Install

```bash
pip install tdata-reader
```

The only runtime dependency is `telethon`. Telethon's pure-Python AES
implementation is used as a fallback, so `cryptg`/`tgcrypto` are
optional — install one of them for a noticeable speed-up if you plan to
also use the resulting client at scale.

## Usage

```python
from tdata_reader import read_tdata

acc = read_tdata("/path/to/tdata")            # first account
print(acc.user_id, acc.dc_id)                 # extracted from tdata
print(acc.api_id, acc.api_hash)               # TelegramDesktop preset
print(acc.device_model, acc.system_version)   # ditto

session_string = acc.to_string_session()       # ready for StringSession
```

Plug into Telethon:

```python
from telethon import TelegramClient
from telethon.sessions import StringSession

client = TelegramClient(
    StringSession(session_string),
    **acc.as_init_connection_kwargs(),
)
```

Passcode-protected tdata:

```python
acc = read_tdata("/path/to/tdata", passcode="my-local-passcode")
```

Multi-account tdata (TDesktop supports up to 3 accounts):

```python
from tdata_reader import read_all_tdata

for acc in read_all_tdata("/path/to/tdata"):
    print(acc.user_id, acc.to_string_session())
```

Mask the session as a different official client:

```python
from tdata_reader import read_tdata, TelegramAndroid

acc = read_tdata("/path/to/tdata", api=TelegramAndroid)
# acc.api_id / acc.api_hash / acc.device_model now match TelegramAndroid
```

## Returned data

`TDataAccount` fields:

| Field | Source | Notes |
|---|---|---|
| `user_id` | tdata | Telegram user id |
| `dc_id` | tdata | Main data-center id (1–5) |
| `auth_key` | tdata | 256-byte authorization key for the main DC |
| `dc_ip`, `dc_port` | built-in | Production endpoint for `dc_id` |
| `extra_auth_keys` | tdata | `{dc_id: 256-byte key}` for non-main DCs |
| `api_id`, `api_hash` | API preset | Defaults to `TelegramDesktop` (2040) |
| `device_model`, `system_version`, `app_version` | API preset | Used by Telethon's `initConnection` |
| `lang_code`, `system_lang_code`, `lang_pack` | API preset | Same |

> **Note on device fields.** `device_model`, `system_version`,
> `app_version`, `lang_code`, `system_lang_code` are **not** stored
> inside tdata — Telegram clients send them in `initConnection` at
> runtime. The library exposes the official preset values so that the
> resulting Telethon client looks identical to a real Telegram Desktop.

## Exceptions

All exceptions inherit from `TDataError`:

- `TDataFileNotFound` — required files (`key_data*`, `data*`, …) missing.
- `TDataBadDecryptKey` — wrong passcode or tampered/corrupt encrypted blob.
- `TDataCorrupted` — files are present but their contents don't parse.
- `TDataUnsupportedDc` — account references a DC id not in the
  built-in production endpoint table.

## License

MIT.
