iran-stock 0.1.2
Get access to Iran's stock information
License: MIT
Requires Python: >=3.7, <4

<div dir="rtl">

## [ایران استاک](https://github.com/J-Yaghoubi/iran_stock) 

+ [آشنایی](#این-برنامه-چه-کاری-انجام-می-دهد) 
+ [نصب](#چگونه-آن-را-نصب-کنیم)    
+ [استفاده](#چگونه-از-آن-استفاده-کنیم)
+ [وابستگی ها](#عملکرد-برنامه-به-چه-ابزارهای-جانبی-وابسته-است)        

------------------------

## این برنامه چه کاری انجام می دهد

این ابزار به سایت tsetmc.com متصل شده و اطلاعات نمادهای موجود در بازار سهام ایران را اعم از اطلاعات قیمتی و پارامترهای بنیادی دریافت و در قالب دیتافریم در اختیار کاربران قرار می دهد.     
در پیاده سازی و کدنویسی سعی ما بر این بوده که ابزار را به گونه ای طراحی کنیم که کاربر را از هرگونه پیچیدگی به دور نگه داشته و سهولت استفاده را فراهم کند. طبعا سعی ما بر این است که با حفظ همین استراتژی و به مرور زمان با توجه به نیاز کاربران به گسترش قابلیت ها و امکانات این ابزار پرداخته و در بروزرسانی هایی که 
انجام می دهیم در مسیر پیشرفت و تکمیل پروژه گام برداریم.
        
------------------------

## چگونه آن را نصب کنیم

برای نصب ایران-استاک کافی است که کد زیر را در مفسر پایتون خود وارد کنید تا ابزار از طریق منبع پایتون دریافت و در سیستم شما نصب شود:

<div>

<div dir="ltr">

```bash
pip install iran_stock
```

<div>


<div dir="rtl">

------------------------

## چگونه از آن استفاده کنیم

1. دریافت سابقه قیمتی    

برای دریافت سابقه قیمت ها کافی است تا نماد فارسی سهم و یا کداختصاری انگلیسی آن را در دستور زیر وارد کنید:

<div>

<div dir="ltr">

```python
import iran_stock as tse
data = tse.get('شبندر')
print(data)

# Output
                     Ticker   First    High     Low   Close         Value        Vol  OpenInt TF    Open    Last
Data
2022-01-18  B.A.Oil.Refinie  6300.0  6300.0  6050.0  6150.0  488418040040   79409720     5761  D  6330.0  6210.0
2022-01-17  B.A.Oil.Refinie  6360.0  6450.0  6220.0  6330.0  317806034360   50232054     3932  D  6250.0  6230.0
2022-01-16  B.A.Oil.Refinie  6250.0  6350.0  6180.0  6250.0  296315603010   47391223     4416  D  6380.0  6300.0
2022-01-15  B.A.Oil.Refinie  6480.0  6510.0  6250.0  6380.0  412740989330   64720530     5022  D  6440.0  6270.0
2022-01-12  B.A.Oil.Refinie  6400.0  6550.0  6350.0  6440.0  351551475390   54607185     4374  D  6380.0  6390.0
...                     ...     ...     ...     ...     ...           ...        ...      ... ..     ...     ...
2012-06-30  B.A.Oil.Refinie  1139.0  1139.0  1139.0  1115.0    2119502455    1860845       63  D  1096.0  1139.0
2012-06-27  B.A.Oil.Refinie  1102.0  1130.0  1086.0  1096.0   76405243282   69730343     2728  D  1131.0  1120.0
2012-06-26  B.A.Oil.Refinie  1154.0  1159.0  1117.0  1131.0   52724280106   46616885     2363  D  1163.0  1117.0
2012-06-25  B.A.Oil.Refinie  1160.0  1180.0  1146.0  1163.0   81667019797   70242200     4041  D  1142.0  1150.0
2012-06-24  B.A.Oil.Refinie  1305.0  1305.0  1140.0  1142.0  788084992681  690000000     3292  D  1000.0  1140.0
```

<div>

 
<div dir="rtl">

اگر تمایل دارید در زمان واحد سابقه قیمتی لیستی از چندین سهم مختلف را دریافت کنید لازم است تا نام نمادهای مورد نظر خود را درون یک لیست قرار داده و سپس لیست را به عنوان آرگومان به تابع get وارد کنید.   

<div>

<div dir="ltr">

```python
import iran_stock as tse
tickers = ['شبندر', 'ملت', 'فملی']
data = tse.get(tickers)
```
<div>

<div dir="rtl">

در هنگام دریافت اطلاعات چه در مواردی که در حال دریافت اطلاعات تک سهم هستید و چه در مواقعی که لیستی از سهم ها را برای دانلود انتخاب کرده اید، این امکان وجود دارد که محدوده داده را با کمک تعیین تاریخ شروع و پایان مشخص کنید:

<div>

<div dir="ltr">

```python
import iran_stock as tse
tickers = ['شبندر', 'ملت', 'فملی']
data = tse.get(tickers, start='2018-01-20', end='2022-01-01')
```
<div>

<div dir="rtl">

در هنگام دریافت اطلاعات به این نکته توجه داشته باشید که سایت tsetmc دسترسی پکیج پانداس را محدود کرده و در بسیاری از موارد اجازه نمی دهد داده ها را به صورت مستقیم از طریق این پکیج دریافت کنیم. برای رفع این مشکل ابزار ایران-استاک ابتدا داده ها را به صورت خام دریافت و در قالب یک فایل ذخیره می کند. سپس فایل ذخیره شده را بازخوانی کرده و به صورت دیتافریم پانداس در اختیار کاربر قرار می دهد.
   
<div>


<div dir="rtl">

2. دریافت اطلاعات بنیادی    

برای دریافت اطلاعات بنیادی کافی است تا نماد فارسی سهم و یا کداختصاری انگلیسی آن را در دستور زیر وارد کنید:

<div>

<div dir="ltr">

```python
import iran_stock as tse
data = tse.fund('شبندر')
```

<div>

<div dir="rtl">

اگر تمایل دارید در زمان واحد اطلاعات بنیادی لیستی از چندین سهم مختلف را دریافت کنید لازم است تا نام نمادهای مورد نظر خود را درون یک لیست قرار داده و سپس لیست را به عنوان آرگومان به تابع fund وارد کنید:   

<div>

<div dir="ltr">

```python
import iran_stock as tse
tickers = ['شبندر', 'ملت', 'فملی']
data = tse.fund(tickers)
```
<div>

<div dir="rtl">

<div dir="rtl">

بعد از اینکه اطلاعات بنیادی سهم و یا لیستی از سهم ها را دریافت کردیم می توانید به همه اطلاعات دریافتی به صورت یکجا و یا به تک تک مولفه ها به صورت مجزا دسترسی داشته باشید. اگر می خواهیم تمام داده دریافتی را به صورت یکجا مشاهده کنید کافی است تا محتویات متغیر را چاپ کنید:  

<div>

<div dir="ltr">

```python
print(data)

# Output
                                               value
Ticker                                          شبندر
Title                           پالايش نفت بندرعباس (شبندر)
Market                        بازار اول (تابلوي فرعي) بورس
Sector                  فراورده هاي نفتي، كك و سوخت هسته اي
EPS                                           1312.0
PE                                               4.7
SectorPE                                         4.9
Shares                                  134341922000
FloatingPercent                                 32.0
MarketCap                            826202820300000
AverageVolume                               71546867
BaseVolume                                  18633540
NAV                                              0.0
```
<div>

<div dir="rtl">

و اما برای دسترسی مجزا به مولفه های دریافتی و چاپ آن ها می توانید مانند مثال زیر عمل کنید:

<div>

<div dir="ltr">

```python
print(data.value.Ticker)
print(data.value.Title)
print(data.value.Market)
print(data.value.Sector)
print(data.value.EPS)
print(data.value.PE)
print(data.value.SectorPE)
print(data.value.Shares)
print(data.value.FloatingPercent)
print(data.value.MarketCap)
print(data.value.AverageVolume)
print(data.value.BaseVolume)
print(data.value.NAV)
```
<div>

<div dir="rtl">

3. کار با بانک اطلاعاتی    

جهت تسریع در خوانش اطلاعات و جستجوی لینک نمادهای درخواستی، ایران-استاک از یک پایگاه داده استفاده می کند که در آن لیست تمام نمادهای موجود در بازار بورس و اوراق بهادار ایران ذخیره شده است. هنگامی که برای اولین بار ایران-استاک را به کار می برید،
داده های لازم دریافت و این پایگاه داده ساخته می شود.    
این بانک اطلاعاتی قابلیت بروزرسانی را نیز دارد و اگر نماد جدیدی در بازار سهام درج شود، می تواند خود را با آخرین تغییرات منطبق کند. برای بروزرسانی محتوای پایگاه داده کافی است تا از دستور زیر کمک بگیرید:

<div>

<div dir="ltr">

```python
import iran_stock as tse
tse.update()
```

<div>


<div dir="rtl">

اگر مایل هستید از اطلاعات ذخیره شده در این بانک اطلاعاتی مطلع شوید، دستور زیر به شما کمک خواهد کرد:    

<div>

<div dir="ltr">

```python
import iran_stock as tse
data = tse.check()
print(data)

# Output
                     ID EnTicker PrTicker
0     51656103046466542     QM02    مظنه2
1     26402398488556706     QM02    مظنه4
2     16256689301150612     QM03   مظنه32
3     24571827372990193     QM03   مظنه34
4     50926374665517412     QM04   مظنه42
...                 ...      ...      ...
6865  25559236668122210     ROBA     کهربا
6866  51200575796028449     SAHR   سحرخیز
6867  57013080981487913     SBBZ      سبز
6868  32469128621155736     ZARA     مثقال
6869  33254899395816171     ZARF      زر
```

<div>


<div dir="rtl">

4. کمی بیشتر   

اگر احساس می کنید توضیحاتی که تا اینجا در مورد چگونگی کار با ایران-استاک داده شده است، برای آشنایی با نحوه کار آن کافی نیست، می توانید به پوشه مثال ها مراجعه کرده و نمونه های بیشتری از نحوه کار با این ماژول را مشاهده کنید.

<div>


<div dir="rtl">

------------------------


## عملکرد برنامه به چه ابزارهای جانبی وابسته است

ایران-استاک برای اینکه بتواند به وظایف خود به درستی عمل کند نیاز دارد تا ابزارهای زیر نیز در سیستم شما نصب شده باشند. البته نیاز نیست شخصا به نصب آن ها اقدام کنید زیرا هنگام نصب ایران-استاک همگی به صورت خودکار نصب خواهند شد:

<div>

<div dir="ltr">

+ [BeautifulSoup](https://pypi.org/project/beautifulsoup4)        
+ [Requests](https://pypi.org/project/requests/)        
+ [Pandas](https://pypi.org/project/pandas/)

<div>