.. image:: https://github.com/5j9/tsetmc/actions/workflows/pytest.yml/badge.svg
:alt: Pytest Status
:target: https://github.com/5j9/tsetmc/actions/workflows/pytest.yml
An ``async`` Python library to fetch data from https://tsetmc.com/.
Installation
------------
Requires Python 3.13 or later.
``pip install tsetmc``
Overview
--------
Let's start with a simple script:
.. code-block:: python
import asyncio
from tsetmc.instruments import Instrument
async def main():
inst = await Instrument.from_l18('فملی')
info = await inst.info()
print(info)
asyncio.run(main())
The ``Instrument`` class provides many methods for getting information about an instrument.
The following code blocks try to demonstrate some of its capabilities.
Note: You need an asyncio capable REPL, like ``python -m asyncio`` or `IPython`_, to run the following code samples, otherwise you'll have to run them inside an async function like the sample code above.
.. code-block:: python
>>> from tsetmc.instruments import Instrument
>>> inst = await Instrument.from_l18('فملی')
>>> await inst.info()
{'eps': {'epsValue': None,
'estimatedEPS': '721',
'sectorPE': 12.02,
'psr': 1472.8279},
'sector': {'dEven': 0, 'cSecVal': '27 ', 'lSecVal': 'فلزات اساسی'},
'staticThreshold': {'insCode': None,
'dEven': 0,
'hEven': 0,
'psGelStaMax': 8270.0,
'psGelStaMin': 7190.0},
'minWeek': 7630.0,
'maxWeek': 7970.0,
'minYear': 4630.0,
'maxYear': 10670.0,
'qTotTran5JAvg': 179233329.0,
'kAjCapValCpsIdx': '43',
'dEven': 0,
'topInst': 1,
'faraDesc': '',
'contractSize': 0,
'nav': 0.0,
'underSupervision': 0,
'cValMne': None,
'lVal18': 'S*I. N. C. Ind.',
'cSocCSAC': None,
'lSoc30': None,
'yMarNSC': None,
'yVal': '300',
'insCode': '35425587644337450',
'lVal30': 'ملی\u200c صنایع\u200c مس\u200c ایران\u200c',
'lVal18AFC': 'فملی',
'flow': 1,
'cIsin': 'IRO1MSMI0000',
'zTitad': 600000000000.0,
'baseVol': 15584416,
'instrumentID': 'IRO1MSMI0001',
'cgrValCot': 'N1',
'cComVal': '1',
'lastDate': 0,
'sourceID': 0,
'flowTitle': 'بازار بورس',
'cgrValCotTitle': 'بازار اول (تابلوی اصلی) بورس'}
Getting the latest price information:
.. code-block:: python
>>> await inst.closing_price_info()
{'instrumentState': {'idn': 0,
'dEven': 0,
'hEven': 0,
'insCode': None,
'cEtaval': 'A ',
'realHeven': 0,
'underSupervision': 0,
'cEtavalTitle': 'مجاز'},
'instrument': None,
'lastHEven': 170725,
'finalLastDate': 20230524,
'nvt': 0.0,
'mop': 0,
'thirtyDayClosingHistory': None,
'priceChange': 0.0,
'priceMin': 7630.0,
'priceMax': 7900.0,
'priceYesterday': 7730.0,
'priceFirst': 7750.0,
'last': True,
'id': 0,
'insCode': '0',
'dEven': 20230524,
'hEven': 170725,
'pClosing': 7700.0,
'iClose': False,
'yClose': False,
'pDrCotVal': 7670.0,
'zTotTran': 7206.0,
'qTotTran5J': 84108817.0,
'qTotCap': 648015842640.0}
Getting the daily trade history for the last n days: (as a DataFrame)
.. code-block:: python
>>> await inst.daily_closing_price(n=2)
priceChange priceMin priceMax ... zTotTran qTotTran5J qTotCap
0 30.0 7490.0 7600.0 ... 4555.0 75649965.0 5.689944e+11
1 10.0 7500.0 7590.0 ... 4614.0 83570336.0 6.276337e+11
[2 rows x 17 columns]
Getting adjusted daily prices:
.. code-block:: python
>>> await 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 intraday data for a specific date:
.. code-block:: python
>>> await inst.on_date(20210704).states() # a dataframe:
idn dEven hEven insCode cEtaval realHeven underSupervision cEtavalTitle
0 0 0 1 0 A 94838 0 None
Searching for an instrument:
.. code-block:: python
>>> await Instrument.from_search('چادرملو')
Instrument(18027801615184692, 'کچاد')
The ``instruments.price_adjustments`` function gets all the price adjustments for a specified flow.
The `market_watch`_ module contains several function to fetch market watch data. They include:
* ``market_watch_init``
* ``market_watch_plus``
* ``closing_price_all``
* ``client_type_all``
* ``key_stats``
* ``ombud_messages``
* ``status_changes``
Use ``market_watch.MarketWatch`` for watching the market. Here is how:
.. code-block:: python
from asyncio import new_event_loop
from tsetmc.market_watch import MarketWatch
async def listen_to_update_events():
while True:
await market_watch.update_event.wait()
df = market_watch.df
print(df.at['35425587644337450', 'pl']) # last price of فملی
market_watch = MarketWatch()
loop = new_event_loop()
watch_task = loop.create_task(listen_to_update_events())
loop.run_until_complete(market_watch.start())
There are many other functions and methods that are not covered here. Explore the codebase to learn more.
To keep the offline dataset up-to-date, run the `tsetmc.dataset.update()` function periodically (e.g., daily). This dataset acts as a cache for basic information about common instruments.
If you are interested in other information available on tsetmc.com that this library has no API for, please `open an issue`_ for them.
See also
--------
* https://github.com/5j9/fipiran
.. _pandas: https://pandas.pydata.org/
.. _market_watch: http://www.tsetmc.com/Loader.aspx?ParTree=15131F
.. _open an issue: https://github.com/5j9/tsetmc/issues
.. _IPython: https://ipython.org/
Raw data
{
"_id": null,
"home_page": null,
"name": "tsetmc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "tsetmc, client",
"author": "5j9",
"author_email": "5j9 <5j9@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/2a/dd/e08481d71a79550afa3bff7aaad1f891f71cb8967345a82742f511f470a7/tsetmc-1.0.0.tar.gz",
"platform": null,
"description": ".. image:: https://github.com/5j9/tsetmc/actions/workflows/pytest.yml/badge.svg\n :alt: Pytest Status\n :target: https://github.com/5j9/tsetmc/actions/workflows/pytest.yml\n\nAn ``async`` Python library to fetch data from https://tsetmc.com/.\n\nInstallation\n------------\nRequires Python 3.13 or later.\n\n``pip install tsetmc``\n\nOverview\n--------\nLet's start with a simple script:\n\n.. code-block:: python\n\n import asyncio\n\n from tsetmc.instruments import Instrument\n\n\n async def main():\n inst = await Instrument.from_l18('\u0641\u0645\u0644\u06cc')\n info = await inst.info()\n print(info)\n\n\n asyncio.run(main())\n\n\nThe ``Instrument`` class provides many methods for getting information about an instrument.\nThe following code blocks try to demonstrate some of its capabilities.\n\nNote: You need an asyncio capable REPL, like ``python -m asyncio`` or `IPython`_, to run the following code samples, otherwise you'll have to run them inside an async function like the sample code above.\n\n.. code-block:: python\n\n >>> from tsetmc.instruments import Instrument\n >>> inst = await Instrument.from_l18('\u0641\u0645\u0644\u06cc')\n >>> await inst.info()\n {'eps': {'epsValue': None,\n 'estimatedEPS': '721',\n 'sectorPE': 12.02,\n 'psr': 1472.8279},\n 'sector': {'dEven': 0, 'cSecVal': '27 ', 'lSecVal': '\u0641\u0644\u0632\u0627\u062a \u0627\u0633\u0627\u0633\u06cc'},\n 'staticThreshold': {'insCode': None,\n 'dEven': 0,\n 'hEven': 0,\n 'psGelStaMax': 8270.0,\n 'psGelStaMin': 7190.0},\n 'minWeek': 7630.0,\n 'maxWeek': 7970.0,\n 'minYear': 4630.0,\n 'maxYear': 10670.0,\n 'qTotTran5JAvg': 179233329.0,\n 'kAjCapValCpsIdx': '43',\n 'dEven': 0,\n 'topInst': 1,\n 'faraDesc': '',\n 'contractSize': 0,\n 'nav': 0.0,\n 'underSupervision': 0,\n 'cValMne': None,\n 'lVal18': 'S*I. N. C. Ind.',\n 'cSocCSAC': None,\n 'lSoc30': None,\n 'yMarNSC': None,\n 'yVal': '300',\n 'insCode': '35425587644337450',\n 'lVal30': '\u0645\u0644\u06cc\\u200c \u0635\u0646\u0627\u06cc\u0639\\u200c \u0645\u0633\\u200c \u0627\u06cc\u0631\u0627\u0646\\u200c',\n 'lVal18AFC': '\u0641\u0645\u0644\u06cc',\n 'flow': 1,\n 'cIsin': 'IRO1MSMI0000',\n 'zTitad': 600000000000.0,\n 'baseVol': 15584416,\n 'instrumentID': 'IRO1MSMI0001',\n 'cgrValCot': 'N1',\n 'cComVal': '1',\n 'lastDate': 0,\n 'sourceID': 0,\n 'flowTitle': '\u0628\u0627\u0632\u0627\u0631 \u0628\u0648\u0631\u0633',\n 'cgrValCotTitle': '\u0628\u0627\u0632\u0627\u0631 \u0627\u0648\u0644 (\u062a\u0627\u0628\u0644\u0648\u06cc \u0627\u0635\u0644\u06cc) \u0628\u0648\u0631\u0633'}\n\n\nGetting the latest price information:\n\n.. code-block:: python\n\n >>> await inst.closing_price_info()\n {'instrumentState': {'idn': 0,\n 'dEven': 0,\n 'hEven': 0,\n 'insCode': None,\n 'cEtaval': 'A ',\n 'realHeven': 0,\n 'underSupervision': 0,\n 'cEtavalTitle': '\u0645\u062c\u0627\u0632'},\n 'instrument': None,\n 'lastHEven': 170725,\n 'finalLastDate': 20230524,\n 'nvt': 0.0,\n 'mop': 0,\n 'thirtyDayClosingHistory': None,\n 'priceChange': 0.0,\n 'priceMin': 7630.0,\n 'priceMax': 7900.0,\n 'priceYesterday': 7730.0,\n 'priceFirst': 7750.0,\n 'last': True,\n 'id': 0,\n 'insCode': '0',\n 'dEven': 20230524,\n 'hEven': 170725,\n 'pClosing': 7700.0,\n 'iClose': False,\n 'yClose': False,\n 'pDrCotVal': 7670.0,\n 'zTotTran': 7206.0,\n 'qTotTran5J': 84108817.0,\n 'qTotCap': 648015842640.0}\n\n\nGetting the daily trade history for the last n days: (as a DataFrame)\n\n.. code-block:: python\n\n >>> await inst.daily_closing_price(n=2)\n priceChange priceMin priceMax ... zTotTran qTotTran5J qTotCap\n 0 30.0 7490.0 7600.0 ... 4555.0 75649965.0 5.689944e+11\n 1 10.0 7500.0 7590.0 ... 4614.0 83570336.0 6.276337e+11\n [2 rows x 17 columns]\n\n\nGetting adjusted daily prices:\n\n.. code-block:: python\n\n >>> await inst.price_history(adjusted=True)\n pmax pmin pf pl tvol pc\n date\n 2007-02-04 45 41 45 42 172898994 42\n 2007-02-05 43 43 43 43 10826496 43\n 2007-02-06 44 44 44 44 26850133 44\n 2007-02-07 45 45 45 45 31086849 45\n 2007-02-10 45 45 45 45 40645528 45\n ... ... ... ... ... ...\n 2021-07-12 13340 12840 13110 12860 106208763 13020\n 2021-07-13 13010 12640 12840 12680 66812306 12770\n 2021-07-14 12830 12450 12540 12690 70277940 12670\n 2021-07-17 12960 12550 12800 12640 68542961 12750\n 2021-07-18 12880 12530 12600 12630 88106162 12650\n [3192 rows x 6 columns]\n\n\nGetting intraday data for a specific date:\n\n.. code-block:: python\n\n >>> await inst.on_date(20210704).states() # a dataframe:\n idn dEven hEven insCode cEtaval realHeven underSupervision cEtavalTitle\n 0 0 0 1 0 A 94838 0 None\n\n\nSearching for an instrument:\n\n.. code-block:: python\n\n >>> await Instrument.from_search('\u0686\u0627\u062f\u0631\u0645\u0644\u0648')\n Instrument(18027801615184692, '\u06a9\u0686\u0627\u062f')\n\nThe ``instruments.price_adjustments`` function gets all the price adjustments for a specified flow.\n\n\nThe `market_watch`_ module contains several function to fetch market watch data. They include:\n\n* ``market_watch_init``\n* ``market_watch_plus``\n* ``closing_price_all``\n* ``client_type_all``\n* ``key_stats``\n* ``ombud_messages``\n* ``status_changes``\n\nUse ``market_watch.MarketWatch`` for watching the market. Here is how:\n\n.. code-block:: python\n\n from asyncio import new_event_loop\n\n from tsetmc.market_watch import MarketWatch\n\n\n async def listen_to_update_events():\n while True:\n await market_watch.update_event.wait()\n df = market_watch.df\n print(df.at['35425587644337450', 'pl']) # last price of \u0641\u0645\u0644\u06cc\n\n\n market_watch = MarketWatch()\n loop = new_event_loop()\n watch_task = loop.create_task(listen_to_update_events())\n loop.run_until_complete(market_watch.start())\n\n\n\nThere are many other functions and methods that are not covered here. Explore the codebase to learn more.\n\nTo keep the offline dataset up-to-date, run the `tsetmc.dataset.update()` function periodically (e.g., daily). This dataset acts as a cache for basic information about common instruments.\n\nIf you are interested in other information available on tsetmc.com that this library has no API for, please `open an issue`_ for them.\n\n\nSee also\n--------\n\n* https://github.com/5j9/fipiran\n\n.. _pandas: https://pandas.pydata.org/\n.. _market_watch: http://www.tsetmc.com/Loader.aspx?ParTree=15131F\n.. _open an issue: https://github.com/5j9/tsetmc/issues\n.. _IPython: https://ipython.org/\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 (GPLv3)",
"summary": "a library to retrieve data from tsetmc.com website",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/5j9/tsetmc"
},
"split_keywords": [
"tsetmc",
" client"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "508724c02e9c980d3de2f5bb98d33b260df518386d24e813f709e2fcf78ca836",
"md5": "5cb85136cc2998da13d5f43642d7a9d3",
"sha256": "141ea16f00ed9502e8ba8313851200d92c1172439f3d3ee707f5a9cd3bd712ac"
},
"downloads": -1,
"filename": "tsetmc-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5cb85136cc2998da13d5f43642d7a9d3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 252420,
"upload_time": "2025-10-10T21:53:55",
"upload_time_iso_8601": "2025-10-10T21:53:55.867700Z",
"url": "https://files.pythonhosted.org/packages/50/87/24c02e9c980d3de2f5bb98d33b260df518386d24e813f709e2fcf78ca836/tsetmc-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2adde08481d71a79550afa3bff7aaad1f891f71cb8967345a82742f511f470a7",
"md5": "037d84d8b2fdb80e3eab43f3b2e72a91",
"sha256": "9a08f9e5f1a181937446f5f27e3c8f4515d10056968fcabf14695e8559fdffc5"
},
"downloads": -1,
"filename": "tsetmc-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "037d84d8b2fdb80e3eab43f3b2e72a91",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 249652,
"upload_time": "2025-10-10T21:54:01",
"upload_time_iso_8601": "2025-10-10T21:54:01.374511Z",
"url": "https://files.pythonhosted.org/packages/2a/dd/e08481d71a79550afa3bff7aaad1f891f71cb8967345a82742f511f470a7/tsetmc-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-10 21:54:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "5j9",
"github_project": "tsetmc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tsetmc"
}
JSON
