راهنمای کاربر برای pytse-filter
این راهنمای کاربر به شما کمک میکند تا از پروژه pytse-filter استفاده کنید، کتابخانه ای پایتون که قادر است داده های نمادهای بورس تهران را با استفاده از فیلتر متنی تعریف شده توسط کاربر پردازش کرده و نتایج را برگرداند.

پیش نیازها
برای استفاده از کتابخانه pytse-filter، مطمئن شوید که:

•  پایتون 3 بر روی سیستم شما نصب شده است.

•  بسته های pandas, pandas_ta, requests, و tqdm با استفاده از pip نصب شده اند.

•  بسته pytse-filter از طریق GitHub یا PyPI نصب شده است.

نصب:

شما می توانید pytse-filter را با استفاده از روش های زیر نصب کنید:

pip install pytse_filter

یا برای نسخه آخر مستقیماً از مخزن github:

pip install git+"https://github.com/farhad-mohammadi/pytse-filter.git"

یا مخزن را کلون کرده و از دایرکتوری محلی نصب کنید:

git clone https://github.com/farhad-mohammadi/pytse-filter
cd pytse_filter
pip install .

توجه: کتابخانه های وابسته به طور خودکار همراه با کتابخانه اصلی نصب می شوند.

چگونگی استفاده از کتابخانه pytse-filter
کتابخانه pytse-filter به دو بخش اصلی تقسیم می شود: RealTime و History، که هر دو برای مبتدیان و حرفه ای ها در بخش های مختلف مناسب هستند.

استفاده مبتدی از RealTime
کلاس RealTime را از کتابخانه وارد کرده و متن فیلتر را همانطور که در مثال های زیر نشان داده شده است، ارسال کنید:

from pytse_filter import RealTime

# مثال ۱: نمادهایی که در منفی قدرت خریدار بیشتر از فروشنده است
conditions = 'pl < py and power > 1'
df = RealTime().filter_by_text_condition(conditions)
print(df)
# اختیاری: نتیجه را در یک فایل اکسل ذخیره کنید
# df.to_excel('myfilter.xlsx')

# مثال ۲: نمادهایی با قدرت خریدار به فروشنده بالا و خرید سرانه بیشتر از 30 میلیون تومان
conditions = 'power > 2 and buy_per_capita > 30'
df = RealTime().filter_by_text_condition(conditions)
print(df)
# df.to_excel('myfilter.xlsx')

# مثال ۳: نمادهایی که درصد خرید حقیقی بالا و نسبت فروش حقوقی زیاد است
conditions = 'ind_buy_ratio > 80 and cor_sell_ratio > 50'
df = RealTime().filter_by_text_condition(conditions)
print(df)
# df.to_excel('myfilter.xlsx')

استفاده پیشرفته از RealTime
برای کاربران پیشرفته، امکان پیگیری مداوم داده ها و نظارت بر تغییرات وضعیت خاص در نمادها وجود دارد:

from pytse_filter import RealTime
from time import sleep
import sys

market = RealTime()
sell_queue_symbols = market.filter_by_text_condition('pl == tmin')
if len(sell_queue_symbols) == 0 :
    print('صف فروشی یافت نشد.')
    sys.exit()

sell_queue_symbols = sell_queue_symbols['symbol'].tolist()
print(sell_queue_symbols)

while True:
    sleep(10)  # هر ۱۰ ثانیه چک کنید
    updated_sell_queue_symbols = market.filter_by_text_condition('pl == tmin')
    if len(updated_sell_queue_symbols) == 0 :
        continue
    updated_sell_queue_symbols = updated_sell_queue_symbols['symbol'].tolist()
    for sym in sell_queue_symbols:
        if sym not in updated_sell_queue_symbols:
            print(f'صف فروش {sym} پاک شد')
    sell_queue_symbols = updated_sell_queue_symbols

همچنین امکان تعیین شرایط مختلف با استفاده از RealTimeCondition وجود دارد و می توانید با دریافت داده ها تنها یک بار و استفاده از آرگومان update_data=False، چندین شرط مختلف را به داده ها اعمال کنید.

from pytse_filter import RealTime, RealTimeCondition
import sys

buy_queue_condition = RealTimeCondition('pl == tmax')
sell_queue_condition = RealTimeCondition('pl == tmin')
positive_conditions = RealTimeCondition('pl < tmax and plp > 1')
negative_conditions = RealTimeCondition('pl > tmin and plp < -1')
zero_condition = RealTimeCondition('plp <= 1 and plp >= -1')

market_data = RealTime()
market_data.download()
if not market_data.download_status:
    print("can't download data')")
    sys.exit()

market_data.condition = buy_queue_condition
buy_queue_symbols = market_data.filter_by_obj_condition(update_data= False)

market_data.condition = sell_queue_condition
sell_queue_symbols = market_data.filter_by_obj_condition(update_data= False)

market_data.condition = positive_conditions
positive_symbols = market_data.filter_by_obj_condition(update_data= False)

market_data.condition = negative_conditions
negative_symbols = market_data.filter_by_obj_condition(update_data= False)

market_data.condition = zero_condition
zero_symbols = market_data.filter_by_obj_condition(update_data= False)

symbols_total = len(buy_queue_symbols) + len(sell_queue_symbols) + len(positive_symbols) + len(negative_symbols) + len(zero_symbols)
msg = f"""بازار در یک نگاه:
از مجموع {symbols_total} نماد
{len(buy_queue_symbols)} نماد در صف خرید
{len(sell_queue_symbols)} نماد در صف فروش
{len(positive_symbols)} نماد در محدوده ی مثبت
{len(negative_symbols)} نماد در محدوده ی منفی
{len(zero_symbols)} نماد در محدوده ی صفر تابلو در حال معامله هستند."""

print(msg) # میتوانید متن را به شبکه های اجتماعی خود ارسال کنید.

متدهای اضافی در کلاس RealTime

• get_all_stocks_data
این متد دادههای جاری تمام نمادها را بازیابی میکند، محاسبات لازم را انجام میدهد و دادهها را به صورت یک DataFrame پانداس برمیگرداند.

نحوه استفاده:

from pytse_filter import RealTime

# بازیابی و محاسبه دادهها برای تمام سهامها
df = RealTime().get_all_stocks_data(update_data=True)

پارامتر update_data تعیین میکند که آیا داده های جدید باید دانلود شوند (True) یا از داده های موجود استفاده شود (False).

• get_stocks_data_as_list:
مشابه get_all_stocks_data، اما خروجی را به صورت لیستی از دیکشنری ها برمیگرداند که هر کدام دادههای یک نماد خاص را دربردارند.

نحوه استفاده:
from pytse_filter import RealTime

# دریافت دادهها برای تمام سهامها به صورت لیستی از دیکشنریها
list_of_dict = RealTime().get_stocks_data_as_list(update_data=True)

استفاده از کلاس History
کلاس History در کتابخانه pytse-filter ابزاری قدرتمند برای تحلیل داده های تاریخی سهام است. این امکان را به شما می دهد تا اندیکاتورهای مختلفی را اعمال کرده و محاسباتی را روی خرید و فروشهای حقیقی و حقوقی انجام دهید.

دانلود داده ها
قبل از اعمال فیلترها، نیاز است تا دادهها برای تمام نمادها دانلود و پردازش شوند. این کار با استفاده از متد download_summery انجام می شود:

from pytse_filter import History

# این کار را بعد از ساعت 8 شب اجرا کنید تا داده ها با آخرین اطلاعات بازار بروز شوند
History().download_summery()

بسته به سرعت اینترنت شما، این فرآیند می تواند بین ۲۰ دقیقه تا بیش از یک ساعت طول بکشد. با این حال، پس از بروزرسانی داده ها، آنها به صورت محلی ذخیره میشوند که این امکان را به شما میدهد تا به سرعت فیلترهای متعددی را اعمال کنید.

فیلتر کردن ابتدایی
برای مبتدیان، کلاس History راهی ساده برای فیلتر کردن نمادها بر اساس  اندیکاتورها و الگوهای خرید/فروش ارائه می دهد:

from pytse_filter import History

# مثال: نمادهایی که RSI آنها کمتر از ۳۰ است و همگرایی میانگین متحرک مثبت دارند
conditions = 'rsi < 30 and macd > 0'
df = History().filter_by_text_condition(conditions)
print(df)
# اختیاری: نتیجه را در یک فایل اکسل ذخیره کنید
# df.to_excel('filtered_symbols.xlsx')

استفاده پیشرفته
کاربران پیشرفته می توانند اندیکاتورها و تنظیمات را در فایل inds_setting.py شخصی سازی کنند. همچنین می توانند از متد download_history برای بازیابی تاریخچه هر نماد، اعمال شاخصها و محاسبات، و ذخیره نتایج استفاده کنند:

from pytse_filter import History

# فایل inds_setting.py را با شاخصها و تنظیمات دلخواه خود بروز کنید

# مثال: فیلتر کردن نمادهایی با شاخص جریان نقدی بالا (MFI) و عبور صعودی MACD از سیگنال
conditions = 'mfi > 80 and y_macd < y_signal and macd > signal'
df = History().filter_by_text_condition(conditions)
print(df)
# داده های فیلتر شده را برای تحلیلهای بیشتر ذخیره کنید
# df.to_excel('advanced_filter.xlsx')

ترکیب Realtime و History
برای تحلیل جامع، می توانید داده های زمان واقعی و تاریخی را ترکیب کنید. این به شما امکان میدهد تا نمادهایی که معیارهای تاریخی خاصی را برآورده میکنند را ردیابی کرده و عملکرد آنها را در زمان واقعی نظارت کنید:

from pytse_filter import History, RealTime
from time import sleep

# نمادها را بر اساس RSI تاریخی کمتر از ۴۰ پیش فیلتر کنید
historical_symbols = History().filter_by_text_condition('rsi < 40')
historical_symbols = list(historical_symbols.index)

# این نمادها را در زمان واقعی برای قدرت خریدار بیشتر از ۲ نظارت کنید
while True:
    sleep(10)  # هر ۱۰ ثانیه چک کنید
    current_power_symbols = RealTime().filter_by_text_condition('power > 2')
    current_power_symbols = current_power_symbols['symbol'].tolist()
    for symbol in current_power_symbols:
        if symbol in historical_symbols:
            print(f'RSI تاریخی < 40 و قدرت خریدار فعلی > 2 برای {symbol}')

این رویکرد به معامله گران امکان میدهد تا سیستمی را راه اندازی کنند که زمانی که نمادهای قوی تاریخی علاقه خرید قابل توجهی در بازار فعلی نشان می دهند، آنها را مطلع سازد و فرصتی بالقوه برای معامله فراهم کند.

متدهای اضافی در کلاس History

• download_history
این متد تاریخچه یک نماد را بازیابی میکند، محاسبات و تحلیلهای شاخصها را انجام میدهد و نتیجه را برمیگرداند. همچنین خروجی را به صورت یک فایل اکسل در پوشه تاریخچه ذخیره میکند.

نحوه استفاده:
from pytse_filter import History

# دانلود و پردازش دادههای تاریخی برای یک نماد
df = History().download_history(symbol= 'خودرو, length=-1, calc_inds=True, calc_client=True)

پارامترها:
•  symbol: نام نماد
•  length: تعداد نقاط داده ای که باید بازیابی شوند. -1 نشاندهنده کل تاریخچه است.
•  calc_inds: آیا محاسبه شاخصها انجام شود (True یا False).
•  calc_client: آیا محاسبات حقیقی و حقوقی انجام شود (True یا False).

نوشتن شرایط
شرط یک رشته متنی است که معیارهای فیلتر کردن داده های سهام را تعریف می کند. از قوانین نحوی زیر استفاده کنید:

•  از متغیرهایی که در فایلهای RealTimeVariables.xlsx و HistoryVariable.xlsx لیست شده اند، استفاده کنید.

•  از عملگرهای مقایسه ای استفاده کنید: ==, !=, <, <=, >, >=.

•  مقایسه ها را با استفاده از عملگرهای منطقی ترکیب کنید: and, or.

•  برای تغییر اولویت عملگرها، مقایسه ها را با پرانتز گروه بندی کنید.

مجوز
پروژه pytse-filter تحت مجوز MIT است. برای جزئیات بیشتر به فایل LICENSE مراجعه کنید.
