Metadata-Version: 2.4
Name: tdatabase-2
Version: 2.0
Summary: Tdatabase a Iranian databse Framework
Author: Tahagaga
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: license-file
Dynamic: requires-python
Dynamic: summary

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='ali@test.com'
)

# اضافه کردن کاربر دوم
tdatabase2.add_value(
    username='sara', 
    password='456', 
    money=500, 
    gmail='sara@test.com'
)

----

🔍 ۴. استخراج داده‌ها (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} تومان")

