Metadata-Version: 2.1
Name: tsetmc
Version: 0.32.7
Summary: a library to retrieve data from tsetmc.com website
Home-page: https://github.com/5j9/tsetmc
Author: 5j9
Author-email: 5j9@users.noreply.github.com
License: GNU General Public License v3 (GPLv3)
Keywords: tsetmc,client
Platform: UNKNOWN
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Internet
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE

A Python library to fetch data from http://tsetmc.com.

Note: The API is provisional and may change without deprecation.

Installation
------------
Requires Python 3.9+.

``pip install tsetmc``

Overview
--------

The ``Instrument`` class provides methods for getting information about an instrument. The following code block tries to demonstrate its capabilities.

Please review the abbreviations described at https://cdn.tsetmc.com/Site.aspx?ParTree=151713 . Many of the parameters/keys/column-names/etc are chosen from those abbreviations. If you can't figure out the meaning of any of them, please open an issue.

.. code-block:: python

    >>> from tsetmc.instruments import Instrument
    >>> inst = Instrument.from_l18('فملی')
    >>> # getting the static data available in the main page of the symbol
    >>> inst.page_data(general=True, trade_history=True, related_companies=True)
    {'bvol': 9803922,
     'cisin': 'IRO1MSMI0000',
     'cs': 27,
     'eps': 1339,
     'sps': 2452.07,
     'flow': 1,
     'free_float': 33,
     'group_code': 'N1',
     'isin': 'IRO1MSMI0001',
     'l18': 'فملی',
     'l30': 'ملی\u200c صنایع\u200c مس\u200c ایران\u200c',
     'flow_name': 'بازار اول (تابلوی اصلی) بورس',
     'month_average_volume': 80515596,
     'sector_name': 'فلزات اساسی',
     'sector_pe': 8.9,
     'tmax': 12650.0,
     'tmin': 11450.0,
     'week_max': 12380.0,
     'week_min': 11770.0,
     'year_max': 39810.0,
     'year_min': 0.0,
     'z': 200000000000,
     'trade_history':                  pc       py     pmin     pmax    tno       tvol          tval
     date
     2021-07-04  12050.0  12040.0  11770.0  12190.0  10504   60085175  7.239613e+11
     2021-07-03  12040.0  12240.0  11800.0  12380.0  14905   88571671  1.066283e+12
     2021-06-30  12240.0  12240.0  12180.0  12370.0  11639   61924440  7.580286e+11
     2021-06-29  12240.0  12140.0  12110.0  12410.0  13153   80738158  9.886263e+11
     2021-06-28  12140.0  12220.0  11990.0  12290.0  12556   69479692  8.434176e+11
     2021-06-27  12220.0  12420.0  12040.0  12440.0  18830   93937722  1.148373e+12
     2021-06-26  12420.0  12310.0  12120.0  12600.0  25260  155751582  1.934123e+12
     2021-06-23  12310.0  11830.0  12020.0  12420.0  23635  204263514  2.514120e+12
     2021-06-22  11830.0  11540.0  11530.0  12110.0  24234  170353210  2.014437e+12,
     'related_companies': [
        Instrument(46348559193224090, 'فولاد'),
        Instrument(35425587644337450, 'فملی'),
        Instrument(45507655586782998, 'فجهان'),
        Instrument(9211775239375291, 'ذوب'),
        ...]}
    >>> # getting the latest price information
    >>> inst.info()
    {'timestamp': '12:30:00',
     'status': 'A ',
     'last_info_datetime': datetime.datetime(2021, 7, 5, 12, 30),
     'pl': 12250,
     'pc': 12210,
     'pf': 12140,
     'py': 12050,
     'pmin': 12340,
     'pmax': 12100,
     'tno': 10904,
     'tvol': 57477120,
     'tval': 701852286450}
    >>> # getting the daily trade history for the last n days (as a DataFrame)
    >>> inst.trade_history(top=2)
                   pmax     pmin       pc  ...          tval      tvol    tno
    date                                   ...
    2021-07-18  12880.0  12530.0  12650.0  ...  1.114773e+12  88106162  14485
    2021-07-17  12960.0  12550.0  12750.0  ...  8.740106e+11  68542961  14327
    [2 rows x 9 columns]
    >>> # getting adjusted daily prices
    >>> inst.price_history(adjusted=True)
                 pmax   pmin     pf     pl       tvol     pc
    date
    2007-02-04     45     41     45     42  172898994     42
    2007-02-05     43     43     43     43   10826496     43
    2007-02-06     44     44     44     44   26850133     44
    2007-02-07     45     45     45     45   31086849     45
    2007-02-10     45     45     45     45   40645528     45
               ...    ...    ...    ...        ...    ...
    2021-07-12  13340  12840  13110  12860  106208763  13020
    2021-07-13  13010  12640  12840  12680   66812306  12770
    2021-07-14  12830  12450  12540  12690   70277940  12670
    2021-07-17  12960  12550  12800  12640   68542961  12750
    2021-07-18  12880  12530  12600  12630   88106162  12650
    [3192 rows x 6 columns]
    >>> # getting legal/natural client types (the result is a DataFrame)
    >>> inst.client_type()
                n_buy_count  l_buy_count  ...  n_sell_value  l_sell_value
    date                                  ...
    2021-07-04         4447           14  ...  586457311950  137504028420
    2021-07-03         5890           23  ...  994298662870   71984465160
    2021-06-30         5032           19  ...  637609524840  120419036770
    2021-06-29         5851           12  ...  562034366100  426591980560
    2021-06-28         5349           17  ...  767532788130   75884839930
                     ...          ...  ...           ...           ...
    2008-12-02            0            1  ...         53664             0
    2008-12-01            0            1  ...             0        212750
    2008-11-30            2            1  ...       2565810             0
    2008-11-29            1            0  ...       4521000             0
    2008-11-26            1            1  ...       1487409         46600
    [2715 rows x 12 columns]
    >>> # getting the data in identification (شناسه) tab of the symbol
    >>> inst.identification()
    {'بازار': 'بازار اول (تابلوی اصلی) بورس',
     'زیر گروه صنعت': 'تولید فلزات گرانبهای غیرآهن',
     'نام شرکت': 'ملی\u200c صنایع\u200c مس\u200c ایران\u200c\u200c',
     'نام لاتین شرکت': 'S*I. N. C. Ind.',
     'نماد 30 رقمی فارسی': 'ملی\u200c صنایع\u200c مس\u200c ایران\u200c',
     'نماد فارسی': 'فملی',
     'کد 12 رقمی شرکت': 'IRO1MSMI0000',
     'کد 12 رقمی نماد': 'IRO1MSMI0001',
     'کد 4 رقمی شرکت': 'MSMI',
     'کد 5 رقمی نماد': 'MSMI1',
     'کد تابلو': '1',
     'کد زیر گروه صنعت': '2720',
     'کد گروه صنعت': '27',
     'گروه صنعت': 'فلزات اساسی'}
    >>> # getting the share/unit holders
    >>> inst.holders()
                                        سهامدار/دارنده  ...            id_cisin
    0    سازمان توسعه ونوسازی معادن وصنایع معدنی ایران  ...    104,IRO1MSMI0000
    1    موسسه صندوق بازنشستگی شرکت ملی صنایع مس ایران  ...    770,IRO1MSMI0000
    2           شرکت سرمایه گذاری صدرتاءمین-سهامی عام-  ...    492,IRO1MSMI0000
    3   شرکت سرمایه گذاری توسعه معادن وفلزات-سهامی عام  ...    460,IRO1MSMI0000
    4                          شرکت صبامیهن-سهامی خاص-  ...  48312,IRO1MSMI0000
    5                     شرکت س اتهران س.خ-م ک م ف ع-  ...   1064,IRO1MSMI0000
    6               شرکت س اخراسان رضوی س.خ-م ک م ف ع-  ...   1065,IRO1MSMI0000
    7         شرکت واسط مالی آذرچهارم-بامسئولیت محدود-  ...  60545,IRO1MSMI0000
    8            شرکت سرمایه گذاری آتیه صبا-سهامی خاص-  ...    788,IRO1MSMI0000
    9      موسسه صندوق بازنشستگی،وظیفه،ازکارافتادگی وپ  ...   7638,IRO1MSMI0000
    10           شرکت سرمایه گذاری فرهنگیان-سهامی خاص-  ...    515,IRO1MSMI0000
    11        شرکت توسعه ومدیریت سرمایه صبا-سهامی خاص-  ...  22650,IRO1MSMI0000
    12    شرکت سرمایه گذاری آتیه اندیشان مس-سهامی عام-  ...    413,IRO1MSMI0000
    13                     شرکت س افارس س.خ-م ک م ف ع-  ...   2674,IRO1MSMI0000
    14                  شرکت س اخوزستان س.خ-م ک م ف ع-  ...   2662,IRO1MSMI0000
    15                   شرکت س ااصفهان س.خ-م ک م ف ع-  ...   1063,IRO1MSMI0000
    16           شرکت س اآذربایجان شرقی س.خ-م ک م ف ع-  ...   2663,IRO1MSMI0000
    17                 شرکت س امازندران س.خ-م ک م ف ع-  ...   2675,IRO1MSMI0000
    18                    شرکت س اکرمان س.خ-م ک م ف ع-  ...   2665,IRO1MSMI0000
    19       موسسه صندوق بیمه اجتماعی روستائیان وعشایر  ...    771,IRO1MSMI0000
    20      شرکت گروه توسعه مالی مهرآیندگان-سهامی عام-  ...  21630,IRO1MSMI0000
    [21 rows x 5 columns]
    >>> # getting information of a specific share/unit holder
    >>> inst.holder('21630,IRO1MSMI0000', history=True, other_holdings=True)
    (                shares
     date
     2021-02-17  2003857980
     2021-02-18  2003857980
     2021-02-21  2003857980
     2021-02-22  2003857980
     2021-02-23  2003857980
     ...                ...
     2021-06-29  2003857980
     2021-06-30  2003857980
     2021-07-01  2003857980
     2021-07-04  2003857980
     2021-07-05  2003857980

     [90 rows x 1 columns],
                                                  name      shares  percent
     ins_code
     778253364357513                          بانک ملت  4161561525     2.00
     26014913469567886       سرمایه‌گذاری‌غدیر(هلدینگ‌  3356161798     4.66
     70270965300262393                      بیمه البرز  2805270000    19.44
     35700344742885862            معدنی و صنعتی گل گهر  2093472351     2.81
     35425587644337450          ملی‌ صنایع‌ مس‌ ایران‌  2003857980     1.00
     47302318535715632                بانک‌اقتصادنوین‌  1242200000     4.08
     45050389997905274                       بانک سینا  1015663732     4.00
     57309221039930244  سرمایه گذاری توسعه صنعت وتجارت   978026662    16.30
     29860265627578401                        بیمه  ما   623740333    15.59
     47996917271187218                 بانک‌ کارآفرین‌   500000000     1.86
     15521712617204216            سیمان فارس و خوزستان   337500000     6.00
     70289374539527245          قطعات‌ اتومبیل‌ ایران‌   259990000     4.19
     43622578471330344               گروه دارویی سبحان   183381668     5.65
     3863538898378476              سرمایه‌گذاری‌ مسکن‌   182160000     3.31
     25514780181345713   سرمایه‌ گذاری‌ ساختمان‌ایران‌   157816359    14.47
     15282093177363578      مهندسی و ساختمان صنایع نفت   129290612     5.13
     35669480110084448                   سیمان‌سپاهان‌   126674401     5.17
     12387472624849835                 داروسازی‌ اسوه‌   118276522    15.77
     57944184894703821    سرمایه‌ گذاری‌ البرز(هلدینگ‌   114588426     2.38
     7711282667602555                   پتروشیمی شازند   101805550     1.26
     60095061789823130  نهادهای مالی بورس اوراق بهادار    87997324     5.60
     6757220448540984                     سیمان‌ شمال‌    67919940     5.26
     30829203706095076                   سیمان‌ تهران‌    53400000     3.05
     59607545337891226                   به پرداخت ملت    36391574     1.21
     52220424531578944                      سیمان‌غرب‌    32151333     6.43
     33931218652865616        سرمایه‌گذاری‌ صنعت‌ نفت‌    30949707     1.87
     39807886630843041          تولید برق عسلویه  مپنا    30270982     4.15
     29747059672582491                  سیمان‌هرمزگان‌    29288000     2.70
     26997316501080743                     سیمان‌ شرق‌    29000000     1.09
     41974758296041288                   سیمان خوزستان    24338461     1.73
     17939384202383793  شرکت سرمایه گذاری مسکن شمالغرب    18333333     1.52
     10919655792568926   نهادهای مالی بورس کالای ایران    18324997     1.88
     28253678449273505              کشتیرانی دریای خزر    15600000     1.44
     11432067920374603                  داروسازی‌ سینا    13930853     1.74
     11964419322927535                    سیمان‌شاهرود    12400000     1.53
     59598536122397373        صندوق س.سپهرخبرگان نفت-د     8310000     1.66
     8603978909726038        ص.س.جسورانه فناوری آرمانی       50000     8.33
     57585821705408565              ص.ج.فیروزه10%تادیه       30000     6.00)
    >>> # getting intraday data
    >>> inst.intraday(
        date=20210704,
        general=False,
        thresholds=False,
        closings=False,
        candles=False,
        states=True,
        trades=True,
        holders=False,
        yesterday_holders=False,
        client_types=True,
        best_limits=True,
    )  # the result is too long and not shown here
    >>> # getting the history of price adjustments
    >>> inst.adjustments()  # the result is a DataFrame
                       date  adj_pc     pc
    0   1399-05-01 00:00:00   35720  35970
    1   1398-04-26 00:00:00    4269   4419
    2   1397-10-02 00:00:00    2880   3744
    3   1397-04-20 00:00:00    3121   3271
    4   1396-08-08 00:00:00    1977   2173
    5   1396-05-01 00:00:00    1534   1884
    6   1395-04-29 00:00:00    1344   1397
    7   1395-04-22 00:00:00    1397   1597
    8   1394-06-30 00:00:00    1298   1378
    9   1393-09-11 00:00:00    2321   2639
    10  1393-04-24 00:00:00    2377   2777
    11  1392-03-20 00:00:00    2872   4774
    12  1392-03-19 00:00:00    4774   5794
    13  1391-04-06 00:00:00    3959   4659
    14  1390-04-14 00:00:00    4911  12991
    15  1390-04-14 00:00:00   12991  15241
    16  1389-04-12 00:00:00    6494   7694
    17  1388-04-24 00:00:00    4827   5627
    >>> Instrument.from_search('توسعه اندوخته آینده')
    Instrument(11427939669935844, 'اطلس')


The functions defined within the ``market_watch`` module can be used to fetch the data related to creating `filters on tsetmc.com`_:

* ``market_watch_init``
* ``closing_price_all``
* ``client_type_all``
* ``key_stats``


The ``instruments.price_adjustments`` function gets all the price adjustments for a specified flow.


If you are interested in other information that are available on tsetmc.com but this library has no API for, please `open an issue`_ for them on github.


See also
--------

* https://github.com/5j9/fipiran


.. _pandas: https://pandas.pydata.org/
.. _filters on tsetmc.com: http://www.tsetmc.com/Loader.aspx?ParTree=15131F
.. _open an issue: https://github.com/5j9/tsetmc/issues


