balenova 0.3.0__tar.gz

balenova-0.3.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+protocol/traces/
+protocol/live-*/
+protocol/browser-profile/
+sessions/
+.private/

balenova-0.3.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Bale Async contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

balenova-0.3.0/NOTICE

@@ -0,0 +1,5 @@
+The public API and behavior were informed by balejs:
+https://github.com/Zellias/balejs
+
+balejs is MIT licensed, Copyright (c) 2026 Hossein Rangani.
+

balenova-0.3.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: balenova
+Version: 0.3.0
+Summary: A friendly Python client for Bale accounts
+Project-URL: Homepage, https://github.com/iliasync/balenova
+Project-URL: Documentation, https://github.com/iliasync/balenova#readme
+Project-URL: Repository, https://github.com/iliasync/balenova
+Project-URL: Issues, https://github.com/iliasync/balenova/issues
+Author: iliasync
+License: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: asyncio,bale,client,messaging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: protobuf<8,>=7.35.1
+Requires-Dist: websockets<17,>=13
+Provides-Extra: dev
+Requires-Dist: grpcio-tools<2,>=1.83; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: types-protobuf>=6.30; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# BaleNova
+
+کار با حساب بله در Python، با یک API ساده و قابل‌فهم.
+
+## نصب
+
+```bash
+pip install balenova
+```
+
+Python 3.10 یا جدیدتر لازم است.
+
+## شروع در کمتر از یک دقیقه
+
+یک فایل به نام `main.py` بسازید:
+
+```python
+from balenova import Client, events, filters
+
+app = Client("my_account")
+
+
+@app.on(events.NewMessage, filters.command("start"))
+async def start(event):
+    await event.reply("سلام! من آماده‌ام 🌱")
+
+
+app.run_forever()
+```
+
+سپس اجرا کنید:
+
+```bash
+python main.py
+```
+
+بار اول شماره، کد ورود و در صورت نیاز رمز دومرحله‌ای پرسیده می‌شود. دفعات بعد
+ورود ذخیره‌شده استفاده خواهد شد.
+
+## پیام‌ها
+
+```python
+@app.on(events.NewMessage, filters.private & filters.text)
+async def new_message(event):
+    print(event.text)
+    print(event.sender_id)
+    print(event.chat.id)
+
+    await event.answer("پیامت رسید")
+    await event.reply("این پیام به‌صورت پاسخ ارسال شد")
+```
+
+فیلترها را می‌توان با `&`، `|` و `~` ترکیب کرد:
+
+```python
+only_commands = filters.incoming & filters.private & filters.command("help")
+```
+
+## همهٔ به‌روزرسانی‌ها به‌صورت کلاس
+
+هر به‌روزرسانی یک شیء مشخص است:
+
+- `events.NewMessage` برای پیام تازه
+- `events.MessageSent` برای تأیید ارسال
+- `events.RawUpdate` برای موارد دیگری که دادهٔ آن‌ها دریافت شده است
+- `events.Update` پایهٔ مشترک همهٔ موارد
+
+```python
+@app.on_update
+async def every_update(update):
+    print(update.name)
+    print(update.to_json())
+```
+
+برای گرفتن فقط یک نوع:
+
+```python
+@app.on(events.MessageSent)
+async def sent(update):
+    print(update.to_dict())
+```
+
+## تبدیل نتیجه‌ها به JSON
+
+مدل‌هایی مانند پیام، کاربر، گفت‌وگو و به‌روزرسانی مستقیماً قابل تبدیل‌اند:
+
+```python
+print(event.to_dict())
+print(event.to_json())
+
+me = await client.get_me()
+print(me.to_json())
+```
+
+## میان‌برهای کاربردی
+
+```python
+await client.send("12345|1", "سلام")
+chat = await client.get_entity("username")
+
+async for message in client.iter_messages("12345|1", limit=100):
+    print(message.text)
+
+limits = await client.get_upload_limits()
+```
+
+روی خود پیام نیز میان‌برهای آماده وجود دارد:
+
+```python
+await event.message.respond("سلام")
+await event.message.edit_text("متن جدید")
+await event.message.delete()
+await event.message.react("❤")
+```
+
+نمونه‌های بیشتر در پوشهٔ [`examples`](examples) و راهنمای ساده در
+[`docs/USAGE.md`](docs/USAGE.md) قرار دارند.
+
+## نکتهٔ مهم
+
+این پروژه رسمیِ بله نیست. از حساب آزمایشی شروع کنید، اطلاعات ورود و فایل‌های
+session را منتشر نکنید و مسئولیت استفاده از حساب بر عهدهٔ خود شماست.
+
+## مجوز
+
+MIT — جزئیات حقوقی لازم در فایل [`NOTICE`](NOTICE) نگه‌داری می‌شود.

balenova-0.3.0/README.md

@@ -0,0 +1,126 @@
+# BaleNova
+
+کار با حساب بله در Python، با یک API ساده و قابل‌فهم.
+
+## نصب
+
+```bash
+pip install balenova
+```
+
+Python 3.10 یا جدیدتر لازم است.
+
+## شروع در کمتر از یک دقیقه
+
+یک فایل به نام `main.py` بسازید:
+
+```python
+from balenova import Client, events, filters
+
+app = Client("my_account")
+
+
+@app.on(events.NewMessage, filters.command("start"))
+async def start(event):
+    await event.reply("سلام! من آماده‌ام 🌱")
+
+
+app.run_forever()
+```
+
+سپس اجرا کنید:
+
+```bash
+python main.py
+```
+
+بار اول شماره، کد ورود و در صورت نیاز رمز دومرحله‌ای پرسیده می‌شود. دفعات بعد
+ورود ذخیره‌شده استفاده خواهد شد.
+
+## پیام‌ها
+
+```python
+@app.on(events.NewMessage, filters.private & filters.text)
+async def new_message(event):
+    print(event.text)
+    print(event.sender_id)
+    print(event.chat.id)
+
+    await event.answer("پیامت رسید")
+    await event.reply("این پیام به‌صورت پاسخ ارسال شد")
+```
+
+فیلترها را می‌توان با `&`، `|` و `~` ترکیب کرد:
+
+```python
+only_commands = filters.incoming & filters.private & filters.command("help")
+```
+
+## همهٔ به‌روزرسانی‌ها به‌صورت کلاس
+
+هر به‌روزرسانی یک شیء مشخص است:
+
+- `events.NewMessage` برای پیام تازه
+- `events.MessageSent` برای تأیید ارسال
+- `events.RawUpdate` برای موارد دیگری که دادهٔ آن‌ها دریافت شده است
+- `events.Update` پایهٔ مشترک همهٔ موارد
+
+```python
+@app.on_update
+async def every_update(update):
+    print(update.name)
+    print(update.to_json())
+```
+
+برای گرفتن فقط یک نوع:
+
+```python
+@app.on(events.MessageSent)
+async def sent(update):
+    print(update.to_dict())
+```
+
+## تبدیل نتیجه‌ها به JSON
+
+مدل‌هایی مانند پیام، کاربر، گفت‌وگو و به‌روزرسانی مستقیماً قابل تبدیل‌اند:
+
+```python
+print(event.to_dict())
+print(event.to_json())
+
+me = await client.get_me()
+print(me.to_json())
+```
+
+## میان‌برهای کاربردی
+
+```python
+await client.send("12345|1", "سلام")
+chat = await client.get_entity("username")
+
+async for message in client.iter_messages("12345|1", limit=100):
+    print(message.text)
+
+limits = await client.get_upload_limits()
+```
+
+روی خود پیام نیز میان‌برهای آماده وجود دارد:
+
+```python
+await event.message.respond("سلام")
+await event.message.edit_text("متن جدید")
+await event.message.delete()
+await event.message.react("❤")
+```
+
+نمونه‌های بیشتر در پوشهٔ [`examples`](examples) و راهنمای ساده در
+[`docs/USAGE.md`](docs/USAGE.md) قرار دارند.
+
+## نکتهٔ مهم
+
+این پروژه رسمیِ بله نیست. از حساب آزمایشی شروع کنید، اطلاعات ورود و فایل‌های
+session را منتشر نکنید و مسئولیت استفاده از حساب بر عهدهٔ خود شماست.
+
+## مجوز
+
+MIT — جزئیات حقوقی لازم در فایل [`NOTICE`](NOTICE) نگه‌داری می‌شود.

balenova-0.3.0/docs/USAGE.md

@@ -0,0 +1,151 @@
+# راهنمای سادهٔ BaleNova
+
+## نصب و ورود
+
+```bash
+pip install balenova
+```
+
+```python
+from balenova import Client
+
+app = Client("personal")
+app.run_forever()
+```
+
+برنامه در اولین اجرا اطلاعات ورود را می‌پرسد. پوشهٔ `sessions` را هیچ‌وقت در
+GitHub قرار ندهید.
+
+## پاسخ به پیام
+
+```python
+from balenova import Client, events, filters
+
+app = Client("personal")
+
+
+@app.on(events.NewMessage, filters.incoming & filters.private)
+async def reply(event):
+    await event.reply("سلام 👋")
+
+
+app.run_forever()
+```
+
+## ساخت دستور
+
+```python
+@app.on(events.NewMessage, filters.command("ping"))
+async def ping(event):
+    await event.reply("pong")
+```
+
+دستوری که کاربر می‌فرستد `/ping` است.
+
+## فیلترهای پرکاربرد
+
+```python
+filters.incoming  # پیام دریافتی
+filters.outgoing  # پیام ارسالی خودتان
+filters.private  # گفت‌وگوی خصوصی
+filters.group  # گروه
+filters.channel  # کانال
+filters.text  # متن
+filters.photo  # عکس
+filters.video  # ویدیو
+filters.document  # فایل
+filters.reply  # پیام پاسخ‌دار
+filters.sender(12345)  # فرستندهٔ مشخص
+filters.regex(r"سلام")
+```
+
+نمونهٔ ترکیب:
+
+```python
+photos_from_groups = filters.incoming & filters.group & filters.photo
+```
+
+## ارسال پیام
+
+```python
+await client.send("12345|1", "سلام")
+```
+
+شناسهٔ گفت‌وگو را می‌توانید از `event.chat.id` بگیرید.
+
+## اطلاعات پیام
+
+```python
+print(event.text)
+print(event.sender)
+print(event.sender_id)
+print(event.chat)
+print(event.message.id)
+```
+
+## کارهای آماده روی پیام
+
+```python
+await event.answer("پیام عادی")
+await event.reply("پاسخ به همین پیام")
+await event.delete()
+await event.message.edit_text("ویرایش شد")
+await event.message.seen()
+await event.message.forward("67890|1")
+```
+
+## کاربر و گفت‌وگو
+
+```python
+me = await client.get_me()
+chat = await client.get_entity("username")
+
+print(me.full_name)
+print(chat.to_json() if chat else "پیدا نشد")
+```
+
+## تاریخچه بدون صفحه‌بندی دستی
+
+```python
+async for message in client.iter_messages("12345|1", limit=100):
+    print(message.content)
+```
+
+## JSON
+
+```python
+data = event.to_dict()
+text = event.to_json()
+```
+
+همین دو متد روی `Message`، `User` و `Chat` هم وجود دارد.
+
+## همهٔ رویدادها
+
+```python
+@app.on_update
+async def inspect(update):
+    print(update.name)
+```
+
+یا فقط یک کلاس مشخص:
+
+```python
+@app.on(events.NewMessage)
+async def messages(event):
+    print(event.text)
+```
+
+## اجرای مثال‌های آماده
+
+پس از دریافت سورس پروژه:
+
+```bash
+pip install -e .
+python examples/login.py
+python examples/echo.py
+python examples/commands.py
+python examples/dialogs.py
+```
+
+برای دیدن گزینه‌های هر مثال، `--help` بزنید.

balenova-0.3.0/examples/README.md

@@ -0,0 +1,35 @@
+# مثال‌های BaleNova
+
+همهٔ مثال‌ها کوتاه و مستقل‌اند. ابتدا کتابخانه را نصب کنید:
+
+```bash
+pip install -e .
+```
+
+سپس یکی را اجرا کنید:
+
+```bash
+python examples/login.py
+python examples/echo.py
+python examples/commands.py
+```
+
+در اولین اجرا اطلاعات ورود پرسیده می‌شود و دفعات بعد از فایل ذخیره‌شده در
+`sessions/my_account.session` استفاده خواهد شد.
+
+در مثال‌هایی که `CHAT_ID` یا `GROUP_ID` دارند، مقدار نمونه را با شناسهٔ واقعی
+خودتان جایگزین کنید.
+
+| فایل | کاربرد |
+| --- | --- |
+| `login.py` | ورود و نمایش حساب |
+| `echo.py` | پاسخ خودکار |
+| `commands.py` | دستور `/start` |
+| `messages.py` | ارسال پیام |
+| `dialogs.py` | نمایش گفت‌وگوها |
+| `json_output.py` | خروجی JSON |
+| `updates.py` | مشاهدهٔ رویدادها |
+| `files.py` | ظرفیت آپلود |
+| `groups.py` | اطلاعات گروه |
+| `gifts.py` | اطلاعات کیف پول |
+| `calls.py` | تماس‌های اخیر |

balenova-0.3.0/examples/calls.py

@@ -0,0 +1,13 @@
+"""نمایش تماس‌های اخیر."""
+
+from balenova import Client
+
+app = Client("my_account")
+
+
+async def main(client):
+    calls = await client.get_call_logs()
+    print(calls)
+
+
+app.run_task(main)

balenova-0.3.0/examples/commands.py

@@ -0,0 +1,13 @@
+"""ساخت دستور /start."""
+
+from balenova import Client, events, filters
+
+app = Client("my_account")
+
+
+@app.on(events.NewMessage, filters.command("start"))
+async def start(event):
+    await event.reply("سلام! آماده‌ام 🌱")
+
+
+app.run_forever()

balenova-0.3.0/examples/dialogs.py

@@ -0,0 +1,16 @@
+"""نمایش گفت‌وگوهای حساب."""
+
+from balenova import Client
+
+app = Client("my_account")
+
+
+async def main(client):
+    dialogs = await client.get_all_dialogs_by_type()
+    for kind, chats in dialogs.items():
+        print(f"{kind}: {len(chats)}")
+        for chat in chats[:5]:
+            print(" -", chat.full_name, chat.id)
+
+
+app.run_task(main)

balenova-0.3.0/examples/echo.py

@@ -0,0 +1,13 @@
+"""پاسخ خودکار به پیام‌های خصوصی."""
+
+from balenova import Client, events, filters
+
+app = Client("my_account")
+
+
+@app.on(events.NewMessage, filters.incoming & filters.private & filters.text)
+async def echo(event):
+    await event.reply(f"گفتی: {event.text}")
+
+
+app.run_forever()

balenova-0.3.0/examples/files.py

@@ -0,0 +1,13 @@
+"""نمایش ظرفیت آپلود حساب."""
+
+from balenova import Client
+
+app = Client("my_account")
+
+
+async def main(client):
+    limits = await client.get_upload_limits()
+    print(limits)
+
+
+app.run_task(main)

balenova-0.3.0/examples/gifts.py

@@ -0,0 +1,13 @@
+"""نمایش کیف پول حساب."""
+
+from balenova import Client
+
+app = Client("my_account")
+
+
+async def main(client):
+    wallet = await client.get_wallet()
+    print(wallet.to_json())
+
+
+app.run_task(main)

balenova-0.3.0/examples/groups.py

@@ -0,0 +1,16 @@
+"""نمایش اطلاعات و اعضای یک گروه."""
+
+from balenova import Client
+
+app = Client("my_account")
+GROUP_ID = "12345|2"  # شناسهٔ گروه خودتان
+
+
+async def main(client):
+    group = await client.get_entity(GROUP_ID)
+    members = await client.load_members(GROUP_ID, limit=20)
+    print(group.to_json() if group else "گروه پیدا نشد")
+    print(members["members"])
+
+
+app.run_task(main)

balenova-0.3.0/examples/json_output.py

@@ -0,0 +1,13 @@
+"""تبدیل نتیجه به JSON."""
+
+from balenova import Client
+
+app = Client("my_account")
+
+
+async def main(client):
+    me = await client.get_me()
+    print(me.to_json())
+
+
+app.run_task(main)

balenova-0.3.0/examples/login.py

@@ -0,0 +1,14 @@
+"""ورود و نمایش اطلاعات حساب."""
+
+from balenova import Client
+
+app = Client("my_account")
+
+
+async def main(client):
+    me = await client.get_me()
+    print(me.full_name)
+    print(me.id)
+
+
+app.run_task(main)

balenova-0.3.0/examples/messages.py

@@ -0,0 +1,14 @@
+"""ارسال یک پیام."""
+
+from balenova import Client
+
+app = Client("my_account")
+CHAT_ID = "12345|1"  # شناسهٔ گفت‌وگوی خودتان
+
+
+async def main(client):
+    message = await client.send(CHAT_ID, "سلام از BaleNova")
+    print(message.id)
+
+
+app.run_task(main)

balenova-0.3.0/examples/updates.py

@@ -0,0 +1,14 @@
+"""نمایش رویدادها."""
+
+from balenova import Client
+
+app = Client("my_account")
+
+
+@app.on_update
+async def update_received(update):
+    print(update.name)
+    print(update.to_json())
+
+
+app.run_forever()