tdatabase-2 2.0

Tdatabase a Iranian databse Framework

Guide :

📘 راهنمای استفاده از کتابخونه Tdatabase سلام! به مستندات Tdatabase خوش اومدی. این کتابخونه یک دیتابیس سبک و ساده برای پایتون هست که ساختاری شبیه به SQL داره. با استفاده از این کتابخونه می‌تونی ستون‌ها (Categories) رو تعریف کنی و داده‌ها (Values) رو به راحتی وارد و استخراج کنی.

📦 نصب و راه‌اندازی برای استفاده از این کتابخونه، مطمئن شو که فایل‌های core.py و init.py در پوشه نصب شده‌اند (معمولاً در site-packages).

import tdatabase2

🔑 ۱. اتصال به دیتابیس (Connect) قبل از هر کاری، باید به دیتابیس متصل بشی. برای این کار از تابع connect استفاده می‌کنیم.

پارامترها:

host: آدرس سرور (فقط 'localhost:3309' پشتیبانی می‌شه).

username: نام کاربری دیتابیس (معمولاً 'root123').

password: رمز عبور دیتابیس (معمولاً 'root').

name: نام دیتابیس مورد نظر (مثلاً 'main').

مثال:

اتصال به دیتابیس

if tdatabase2.connect(host='localhost:3309', username='root123', password='root', name='main'): print("Etesal Movafaghiat Amiz Bood.") else: print("Khata Dar Etesal.")

نکته: اگر اتصال موفق باشه، پیام Hi, Tdatabase is active. نمایش داده می‌شه.

---

📂 ۲. تعریف ستون‌ها (Add Category) در Tdatabase، قبل از وارد کردن داده، باید ستون‌ها (فیلدها) رو تعریف کنی. این کار شبیه به CREATE TABLE در SQL هست.

تابع: add_category(category_name)

مثال:

تعریف ستون‌های مختلف

tdatabase2.add_category('username') tdatabase2.add_category('password') tdatabase2.add_category('money') tdatabase2.add_category('gmail') tdatabase2.add_category('anum')

نکته: اگر ستونی از قبل وجود داشته باشه، پیام هشدار نمایش داده می‌شه و خطی ایجاد نمی‌شه.

---

📝 ۳. وارد کردن داده‌ها (Add Value) حالا که ستون‌ها آماده‌ن، می‌تونی داده‌ها رو وارد کنی. این تابع شبیه به INSERT INTO عمل می‌کنه.

تابع: add_value(**kwargs)

می‌تونی هر تعداد ستون و مقدار دلخواه رو به صورت کی‌ورد آرگمنت (key=value) وارد کنی.

ستون anum به صورت خودکار محاسبه و اضافه می‌شه (نیازی نیست دستی وارد کنی).

مثال:

اضافه کردن کاربر اول

tdatabase2.add_value( username='ali', password='123', money=1000, gmail='[e-mail]' )

اضافه کردن کاربر دوم

tdatabase2.add_value( username='sara', password='456', money=500, gmail='[e-mail]' )

---

🔍 ۴. استخراج داده‌ها (Get Data) برای خواندن اطلاعات کاربران، دو تابع اصلی وجود داره:

الف) دریافت تمام اطلاعات یک کاربر (get_user_data) این تابع دیکشنری‌ای از تمام اطلاعات یک کاربر رو برمی‌گردونه.

مثال:

دریافت اطلاعات کامل علی

data = tdatabase2.get_user_data('ali') print(data)

خروجی: {'username': 'ali', 'password': '123', 'money': '1000', ...}

ب) دریافت یک فیلد خاص (get_value) اگر فقط به یک مقدار خاص نیاز داری، از این تابع استفاده کن.

مثال:

دریافت فقط پول علی

money = tdatabase2.get_value('ali', 'money') print(f"Ali's money: {money}")

خروجی: Ali's money: 1000

---

🛠️ ۵. توابع کمکی (Helper Functions) parse_tdb_file() این تابع محتویات فایل دیتابیس رو به صورت یک دیکشنری از لیست‌ها برمی‌گردونه. برای کارهای پیشرفته‌تر مثل نمایش کل جدول مفیده.

مثال:

all_data = tdatabase2.parse_tdb_file() print(all_data)

---

💡 نکات مهم و کاربردی ذخیره خودکار: هر تغییری که با add_category یا add_value ایجاد می‌کنی، بلافاصله روی فایل ذخیره می‌شه.

نوع داده‌ها: تمام مقادیر به صورت رشته (String) ذخیره می‌شن. اگر نیاز به محاسبات عددی داری، قبل از استفاده مقدار رو به int یا float تبدیل کن.

money = int(tdatabase2.get_value('ali', 'money'))

مدیریت خطا: اگر کاربری پیدا نشه، توابع get_user_data و get_value مقدار None رو برمی‌گردونن. همیشه چک کن که مقدار None نباشه.

ساختار فایل: دیتابیس‌ها در مسیر C:\Users{YourName}\AppData\Roaming..Tdatabase\data\ ذخیره می‌شن.

---

🚀 مثال کامل (یک اسکریپت ساده) این یک مثال کامل از نحوه استفاده از کتابخونه در یک برنامه ساده:

import tdatabase2

1. اتصال

if not tdatabase2.connect(host='localhost:3309', username='root123', password='root', name='main'): print("خطا در اتصال. برنامه متوقف می‌شه.") exit()

2. تعریف ستون‌ها (اگر وجود ندارن)

tdatabase2.add_category('username') tdatabase2.add_category('password') tdatabase2.add_category('balance')

3. ثبت نام کاربر جدید

username = input("نام کاربری را وارد کنید: ") password = input("رمز عبور را وارد کنید: ")

tdatabase2.add_value(username=username, password=password, balance=0) print(f"کاربر {username} با موفقیت ثبت شد!")

4. بررسی موجودی

current_balance = tdatabase2.get_value(username, 'balance') print(f"موجودی فعلی شما: {current_balance} تومان")