bursakit 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. bursakit-0.1.1/.gitignore +11 -0
  2. bursakit-0.1.1/CHANGELOG.md +45 -0
  3. bursakit-0.1.1/LICENSE +21 -0
  4. bursakit-0.1.1/PKG-INFO +206 -0
  5. bursakit-0.1.1/README.md +173 -0
  6. bursakit-0.1.1/bursakit/__init__.py +78 -0
  7. bursakit-0.1.1/bursakit/_util.py +64 -0
  8. bursakit-0.1.1/bursakit/cache.py +382 -0
  9. bursakit-0.1.1/bursakit/cli.py +114 -0
  10. bursakit-0.1.1/bursakit/errors.py +69 -0
  11. bursakit-0.1.1/bursakit/macro.py +59 -0
  12. bursakit-0.1.1/bursakit/policy.py +197 -0
  13. bursakit-0.1.1/bursakit/py.typed +0 -0
  14. bursakit-0.1.1/bursakit/router.py +116 -0
  15. bursakit-0.1.1/bursakit/schema.py +195 -0
  16. bursakit-0.1.1/bursakit/sources/__init__.py +8 -0
  17. bursakit-0.1.1/bursakit/sources/_yf.py +97 -0
  18. bursakit-0.1.1/bursakit/sources/base.py +53 -0
  19. bursakit-0.1.1/bursakit/sources/bnm.py +107 -0
  20. bursakit-0.1.1/bursakit/sources/datagovmy.py +63 -0
  21. bursakit-0.1.1/bursakit/sources/yahoo.py +164 -0
  22. bursakit-0.1.1/bursakit/tickers.py +77 -0
  23. bursakit-0.1.1/docs/img/opr-usdmyr.png +0 -0
  24. bursakit-0.1.1/docs/source-terms.md +92 -0
  25. bursakit-0.1.1/docs/spike-go-no-go.md +54 -0
  26. bursakit-0.1.1/pyproject.toml +84 -0
  27. bursakit-0.1.1/tests/__init__.py +0 -0
  28. bursakit-0.1.1/tests/conftest.py +45 -0
  29. bursakit-0.1.1/tests/fixtures/README.md +14 -0
  30. bursakit-0.1.1/tests/fixtures/http/api_bnm_gov_my_public_exchange_rate_JPY_year_2024_month_1_quote_rm_session_1700.json +4 -0
  31. bursakit-0.1.1/tests/fixtures/http/api_bnm_gov_my_public_exchange_rate_USD_year_2024_month_1_quote_rm_session_1700.json +4 -0
  32. bursakit-0.1.1/tests/fixtures/http/api_bnm_gov_my_public_exchange_rate_USD_year_2024_month_2_quote_rm_session_1700.json +4 -0
  33. bursakit-0.1.1/tests/fixtures/http/api_bnm_gov_my_public_opr_year_2023.json +4 -0
  34. bursakit-0.1.1/tests/fixtures/http/api_bnm_gov_my_public_opr_year_2024.json +4 -0
  35. bursakit-0.1.1/tests/fixtures/http/api_data_gov_my_data_catalogue_date_end_2024_01_31_date_date_start_2024_01_01_date_id_exchangerates_daily_1700_include_d.json +4 -0
  36. bursakit-0.1.1/tests/fixtures/http/api_data_gov_my_data_catalogue_date_end_2024_02_29_date_date_start_2024_01_01_date_id_exchangerates_daily_1700_include_d.json +4 -0
  37. bursakit-0.1.1/tests/fixtures/http/index.json +9 -0
  38. bursakit-0.1.1/tests/fixtures/yahoo/history_1155.KL.json +1 -0
  39. bursakit-0.1.1/tests/fixtures/yahoo/screen.json +2420 -0
  40. bursakit-0.1.1/tests/fixtures/yahoo/search_MAYBANK.json +71 -0
  41. bursakit-0.1.1/tests/fixtures/yahoo/search_NOTAREALCO.json +1 -0
  42. bursakit-0.1.1/tests/fixtures/yahoo/search_PUBLIC.json +82 -0
  43. bursakit-0.1.1/tests/fixtures/yahoo/search_TENAGA.json +67 -0
  44. bursakit-0.1.1/tests/record_fixtures.py +96 -0
  45. bursakit-0.1.1/tests/replay.py +85 -0
  46. bursakit-0.1.1/tests/test_api.py +190 -0
  47. bursakit-0.1.1/tests/test_cache.py +319 -0
  48. bursakit-0.1.1/tests/test_cli.py +76 -0
  49. bursakit-0.1.1/tests/test_package.py +11 -0
  50. bursakit-0.1.1/tests/test_policy.py +177 -0
  51. bursakit-0.1.1/tests/test_router.py +118 -0
  52. bursakit-0.1.1/tests/test_schema.py +105 -0
  53. bursakit-0.1.1/tests/test_sources.py +290 -0
  54. bursakit-0.1.1/tests/test_tickers.py +76 -0
  55. bursakit-0.1.1/tests_live/__init__.py +0 -0
  56. bursakit-0.1.1/tests_live/conftest.py +40 -0
  57. bursakit-0.1.1/tests_live/test_live.py +126 -0
@@ -0,0 +1,11 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ dist/
6
+ build/
7
+ .pytest_cache/
8
+ .mypy_cache/
9
+ .ruff_cache/
10
+ .coverage
11
+ htmlcov/
@@ -0,0 +1,45 @@
1
+ # Changelog
2
+
3
+ ## 0.1.1 (unreleased)
4
+
5
+ First release on PyPI. No change to the library.
6
+
7
+ - `pip install bursakit` now works.
8
+ - README links point to GitHub, so they work on the PyPI page.
9
+ - Releases are built and uploaded to PyPI by GitHub Actions.
10
+ - README badges and a chart; a runnable example in `examples/quickstart.ipynb`.
11
+
12
+ ## 0.1.0 (2026-11-18)
13
+
14
+ First release.
15
+
16
+ ### Data
17
+
18
+ - `prices(ticker, start, end)`: daily open, high, low, close and volume, from Yahoo Finance.
19
+ - `dividends(ticker)`: ex-dates and amounts per share in MYR, from Yahoo Finance.
20
+ - `listings()`: Bursa codes with name, company and sector, from Yahoo Finance.
21
+ - `resolve(name)`: turns `1155`, `1155.KL` or `MAYBANK` into the same `Ticker`.
22
+ - `macro.opr()`: Overnight Policy Rate decisions, from the Bank Negara Malaysia Open API.
23
+ - `macro.fx(currency)`: MYR buy, sell and mid rates, from data.gov.my with BNM as the fallback.
24
+
25
+ ### Behaviour
26
+
27
+ - One schema per data type. Every source's answer is checked against it before it is cached or
28
+ returned, so column names and dtypes never depend on which source answered.
29
+ - Local SQLite cache. Past rows are kept and only the missing tail is fetched; today's rows,
30
+ dividends, listings and lookups expire. A changed price history (a split or bonus issue) is
31
+ detected and refetched. A failed refresh keeps what was stored.
32
+ - Requests to each source are spaced out and retried with backoff; waits of 5 s or more are
33
+ logged on the `bursakit` logger.
34
+ - A price day with a missing value is dropped and logged instead of failing the whole range.
35
+ - `df.attrs` records the data type, source, required credit line and a link to the source's
36
+ terms.
37
+ - `bursakit` command line tool for every function, with CSV output.
38
+
39
+ ### Known limitations
40
+
41
+ - Yahoo Finance data is for personal, non-commercial use only and must not be redistributed.
42
+ See [docs/source-terms.md](docs/source-terms.md).
43
+ - `listings()` leaves `market` (Main / ACE / LEAP) empty and uses Yahoo's sector names, not
44
+ Bursa's.
45
+ - Prices and dividends are adjusted for splits and bonus issues by the source.
bursakit-0.1.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 bursakit contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,206 @@
1
+ Metadata-Version: 2.5
2
+ Name: bursakit
3
+ Version: 0.1.1
4
+ Summary: Bursa Malaysia stock data and Malaysian macro series as pandas DataFrames, cached locally.
5
+ Project-URL: Source, https://github.com/MaosterM/bursakit
6
+ Project-URL: Changelog, https://github.com/MaosterM/bursakit/blob/main/CHANGELOG.md
7
+ Project-URL: Source terms, https://github.com/MaosterM/bursakit/blob/main/docs/source-terms.md
8
+ License: MIT
9
+ License-File: LICENSE
10
+ Keywords: bnm,bursa,finance,klse,malaysia,pandas
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Financial and Insurance Industry
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Office/Business :: Financial :: Investment
20
+ Classifier: Typing :: Typed
21
+ Requires-Python: >=3.10
22
+ Requires-Dist: pandas>=2.2
23
+ Requires-Dist: requests>=2.31
24
+ Requires-Dist: yfinance>=0.2.54
25
+ Provides-Extra: dev
26
+ Requires-Dist: mypy>=1.10; extra == 'dev'
27
+ Requires-Dist: pandas-stubs>=2.0; extra == 'dev'
28
+ Requires-Dist: pytest-cov>=5; extra == 'dev'
29
+ Requires-Dist: pytest>=8; extra == 'dev'
30
+ Requires-Dist: ruff>=0.5; extra == 'dev'
31
+ Requires-Dist: types-requests>=2.31; extra == 'dev'
32
+ Description-Content-Type: text/markdown
33
+
34
+ # bursakit
35
+
36
+ [![PyPI](https://img.shields.io/pypi/v/bursakit)](https://pypi.org/project/bursakit/)
37
+ [![Python](https://img.shields.io/pypi/pyversions/bursakit)](https://pypi.org/project/bursakit/)
38
+ [![CI](https://github.com/MaosterM/bursakit/actions/workflows/ci.yml/badge.svg)](https://github.com/MaosterM/bursakit/actions/workflows/ci.yml)
39
+ [![Sources checked nightly](https://img.shields.io/github/actions/workflow/status/MaosterM/bursakit/live.yml?label=sources%20checked%20nightly)](https://github.com/MaosterM/bursakit/actions/workflows/live.yml)
40
+ [![License: MIT](https://img.shields.io/github/license/MaosterM/bursakit)](https://github.com/MaosterM/bursakit/blob/main/LICENSE)
41
+
42
+ Bursa Malaysia stock data and Malaysian macro series as pandas DataFrames.
43
+ Cached locally, one schema per data type, more than one source.
44
+
45
+ ![Overnight Policy Rate and USD/MYR since 2015](https://raw.githubusercontent.com/MaosterM/bursakit/main/docs/img/opr-usdmyr.png)
46
+
47
+ <sub>Made with `bk.macro.opr()` and `bk.macro.fx("USD")`. Source: Bank Negara Malaysia
48
+ ([terms](https://www.bnm.gov.my/terms-of-use-bnm-datasets)); USD/MYR via data.gov.my
49
+ ([CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)). Code in
50
+ [examples/quickstart.ipynb](https://github.com/MaosterM/bursakit/blob/main/examples/quickstart.ipynb).</sub>
51
+
52
+ Status: alpha. Python 3.10 or later.
53
+
54
+ ```bash
55
+ pip install bursakit
56
+ ```
57
+
58
+ Not affiliated with Bursa Malaysia, Bank Negara Malaysia or Yahoo. bursakit ships no data:
59
+ each user fetches their own, under each source's terms (see Sources below).
60
+
61
+ ## Usage
62
+
63
+ ```python
64
+ import bursakit as bk
65
+
66
+ # Daily prices. 1155, "1155.KL" and "MAYBANK" are the same ticker.
67
+ df = bk.prices("MAYBANK", start="2024-01-01", end="2024-12-31")
68
+ # open high low close volume
69
+ # date
70
+ # 2024-01-02 8.89 8.92 8.83 8.92 6414300
71
+ # 2024-01-03 8.92 8.93 8.88 8.89 8678500
72
+
73
+ bk.dividends("1155") # ex-date index, amount per share in MYR
74
+ bk.listings() # code index: name, company, sector, market
75
+ bk.resolve("maybank") # Ticker(code='1155', name='MAYBANK')
76
+
77
+ bk.macro.opr() # Overnight Policy Rate decisions, last 5 years
78
+ bk.macro.fx("USD") # MYR per 1 USD: buy, sell, mid, last 12 months
79
+ ```
80
+
81
+ The second call for the same data reads from the local cache and makes no request.
82
+
83
+ ```python
84
+ bk.prices("1155", start="2020-01-01") # one request
85
+ bk.prices("1155", start="2020-01-01") # none
86
+ bk.prices("1155", start="2020-01-01", refresh=True) # fetch again, replace what is stored
87
+
88
+ bk.cache.info() # location, row counts
89
+ bk.cache.clear() # or bk.cache.clear("prices")
90
+ ```
91
+
92
+ Every DataFrame says where it came from:
93
+
94
+ ```python
95
+ df.attrs # {'kind': 'prices', 'ticker': '1155', 'currency': 'MYR',
96
+ # 'source': 'yahoo', 'attribution': 'Yahoo Finance',
97
+ # 'terms': 'https://legal.yahoo.com/xw/en/yahoo/terms/otos/index.html'}
98
+ ```
99
+
100
+ When you publish or share data, show `attribution` and link to `terms`.
101
+
102
+ ### Command line
103
+
104
+ ```bash
105
+ bursakit prices 1155 --start 2024-01-01 --csv
106
+ bursakit dividends MAYBANK
107
+ bursakit listings --csv --out listings.csv
108
+ bursakit opr --start 2015-01-01
109
+ bursakit fx USD --start 2024-01-01 --csv
110
+ bursakit resolve maybank
111
+ bursakit cache info
112
+ ```
113
+
114
+ ## Schemas
115
+
116
+ Column names and dtypes are the same whichever source answered. Dates are timezone-naive
117
+ Malaysian calendar dates, the index is sorted and unique, money is in MYR.
118
+
119
+ | Function | Index | Columns |
120
+ | --- | --- | --- |
121
+ | `prices` | `date` | `open`, `high`, `low`, `close` (float64), `volume` (int64) |
122
+ | `dividends` | `date` (ex-date) | `amount` (float64, MYR per share) |
123
+ | `listings` | `code` (string) | `name`, `company`, `sector`, `market` (string) |
124
+ | `macro.opr` | `date` (decision date) | `rate`, `change` (float64, percent) |
125
+ | `macro.fx` | `date` | `buy`, `sell`, `mid` (float64, MYR per 1 unit of the currency) |
126
+
127
+ Known gaps: `market` is empty and `sector` uses Yahoo's sector names. Bursa's own
128
+ classification is only available from Bursa, whose terms forbid storing its website content
129
+ without written consent. Prices and dividends are adjusted for
130
+ splits and bonus issues by the source.
131
+
132
+ ## Errors
133
+
134
+ ```python
135
+ from bursakit import TickerNotFound, SourceUnavailable, RateLimited
136
+
137
+ try:
138
+ bk.prices("NOTAREALCO")
139
+ except TickerNotFound as exc:
140
+ print(exc.suggestions)
141
+ ```
142
+
143
+ | Error | Meaning |
144
+ | --- | --- |
145
+ | `TickerNotFound` | No Bursa listing matches. `.suggestions` holds near matches. |
146
+ | `SourceUnavailable` | Every source for that data type failed. `.causes` lists each failure. |
147
+ | `RateLimited` | A source asked us to slow down. Subclass of `SourceUnavailable`; `.retry_after` in seconds. |
148
+
149
+ A source that changes the shape of its response is rejected by the schema check and the next
150
+ source is tried. Nothing unvalidated is written to the cache.
151
+
152
+ A price day with a missing price or volume is dropped and the rest of the range is returned.
153
+ Each dropped day is logged as a warning on the `bursakit` logger.
154
+
155
+ ## Sources
156
+
157
+ | Data | Source order | Terms |
158
+ | --- | --- | --- |
159
+ | prices, dividends, listings, name lookup | Yahoo Finance through `yfinance` | Personal, non-commercial use; no redistribution |
160
+ | `macro.opr` | Bank Negara Malaysia Open API | Free, commercial use and redistribution allowed with credit |
161
+ | `macro.fx` | data.gov.my Open API, then Bank Negara Malaysia Open API | Same as BNM; data.gov.my is CC BY 4.0 |
162
+
163
+ **Yahoo data is for your own use.** Yahoo's terms do not allow automated collection, commercial
164
+ use or redistribution without Yahoo's written permission, and `yfinance` is unofficial. Do not
165
+ publish, sell or serve Yahoo-sourced prices, dividends or listings to others.
166
+
167
+ BNM and data.gov.my data can be shared and used commercially if you credit it: "Source: Bank
168
+ Negara Malaysia" with a link to the BNM dataset terms. `df.attrs` carries both.
169
+ See [docs/source-terms.md](https://github.com/MaosterM/bursakit/blob/main/docs/source-terms.md) for the clauses behind this table.
170
+
171
+ Requests to one source are spaced out. data.gov.my allows 4 requests a minute, so a second
172
+ request within 15 seconds waits. A wait of 5 seconds or more is logged as a warning on the
173
+ `bursakit` logger; `logging.getLogger("bursakit").setLevel("ERROR")` silences it.
174
+ See [docs/spike-go-no-go.md](https://github.com/MaosterM/bursakit/blob/main/docs/spike-go-no-go.md) for what was verified.
175
+
176
+ ## Cache
177
+
178
+ SQLite file under `%LOCALAPPDATA%\bursakit\Cache` on Windows or `~/.cache/bursakit` elsewhere.
179
+ Set `BURSAKIT_CACHE_DIR` to move it.
180
+
181
+ - Price, FX and OPR rows dated before today are kept permanently. Only the missing tail is fetched.
182
+ - Today's rows expire: 15 minutes for prices, 6 hours for FX and OPR.
183
+ - Dividends expire after 24 hours, listings after 7 days, name lookups after 30 days.
184
+ - Each price refresh overlaps the stored history by a week. If the overlap no longer matches
185
+ (a split or bonus issue), the ticker's history is refetched.
186
+ - `refresh=True` replaces what is stored for that ticker or series with the requested range.
187
+ The stored rows are removed only after the new fetch succeeds, so a failed refresh loses nothing.
188
+
189
+ ## Development
190
+
191
+ ```bash
192
+ git clone https://github.com/MaosterM/bursakit
193
+ cd bursakit
194
+ pip install -e ".[dev]"
195
+ pytest # offline, replays recorded responses
196
+ ruff check .
197
+ mypy
198
+ ```
199
+
200
+ Tests block network access. `python tests/record_fixtures.py` re-records the fixtures from
201
+ the live sources.
202
+
203
+ `pytest tests_live` asks the real sources for a little data and checks the answers still fit
204
+ the schemas. It needs network access and is not part of plain `pytest`. A GitHub Actions
205
+ workflow runs it every night; a failure there means a source changed or is down. A test is
206
+ skipped, not failed, when a source rate limits the machine running it.
@@ -0,0 +1,173 @@
1
+ # bursakit
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/bursakit)](https://pypi.org/project/bursakit/)
4
+ [![Python](https://img.shields.io/pypi/pyversions/bursakit)](https://pypi.org/project/bursakit/)
5
+ [![CI](https://github.com/MaosterM/bursakit/actions/workflows/ci.yml/badge.svg)](https://github.com/MaosterM/bursakit/actions/workflows/ci.yml)
6
+ [![Sources checked nightly](https://img.shields.io/github/actions/workflow/status/MaosterM/bursakit/live.yml?label=sources%20checked%20nightly)](https://github.com/MaosterM/bursakit/actions/workflows/live.yml)
7
+ [![License: MIT](https://img.shields.io/github/license/MaosterM/bursakit)](https://github.com/MaosterM/bursakit/blob/main/LICENSE)
8
+
9
+ Bursa Malaysia stock data and Malaysian macro series as pandas DataFrames.
10
+ Cached locally, one schema per data type, more than one source.
11
+
12
+ ![Overnight Policy Rate and USD/MYR since 2015](https://raw.githubusercontent.com/MaosterM/bursakit/main/docs/img/opr-usdmyr.png)
13
+
14
+ <sub>Made with `bk.macro.opr()` and `bk.macro.fx("USD")`. Source: Bank Negara Malaysia
15
+ ([terms](https://www.bnm.gov.my/terms-of-use-bnm-datasets)); USD/MYR via data.gov.my
16
+ ([CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)). Code in
17
+ [examples/quickstart.ipynb](https://github.com/MaosterM/bursakit/blob/main/examples/quickstart.ipynb).</sub>
18
+
19
+ Status: alpha. Python 3.10 or later.
20
+
21
+ ```bash
22
+ pip install bursakit
23
+ ```
24
+
25
+ Not affiliated with Bursa Malaysia, Bank Negara Malaysia or Yahoo. bursakit ships no data:
26
+ each user fetches their own, under each source's terms (see Sources below).
27
+
28
+ ## Usage
29
+
30
+ ```python
31
+ import bursakit as bk
32
+
33
+ # Daily prices. 1155, "1155.KL" and "MAYBANK" are the same ticker.
34
+ df = bk.prices("MAYBANK", start="2024-01-01", end="2024-12-31")
35
+ # open high low close volume
36
+ # date
37
+ # 2024-01-02 8.89 8.92 8.83 8.92 6414300
38
+ # 2024-01-03 8.92 8.93 8.88 8.89 8678500
39
+
40
+ bk.dividends("1155") # ex-date index, amount per share in MYR
41
+ bk.listings() # code index: name, company, sector, market
42
+ bk.resolve("maybank") # Ticker(code='1155', name='MAYBANK')
43
+
44
+ bk.macro.opr() # Overnight Policy Rate decisions, last 5 years
45
+ bk.macro.fx("USD") # MYR per 1 USD: buy, sell, mid, last 12 months
46
+ ```
47
+
48
+ The second call for the same data reads from the local cache and makes no request.
49
+
50
+ ```python
51
+ bk.prices("1155", start="2020-01-01") # one request
52
+ bk.prices("1155", start="2020-01-01") # none
53
+ bk.prices("1155", start="2020-01-01", refresh=True) # fetch again, replace what is stored
54
+
55
+ bk.cache.info() # location, row counts
56
+ bk.cache.clear() # or bk.cache.clear("prices")
57
+ ```
58
+
59
+ Every DataFrame says where it came from:
60
+
61
+ ```python
62
+ df.attrs # {'kind': 'prices', 'ticker': '1155', 'currency': 'MYR',
63
+ # 'source': 'yahoo', 'attribution': 'Yahoo Finance',
64
+ # 'terms': 'https://legal.yahoo.com/xw/en/yahoo/terms/otos/index.html'}
65
+ ```
66
+
67
+ When you publish or share data, show `attribution` and link to `terms`.
68
+
69
+ ### Command line
70
+
71
+ ```bash
72
+ bursakit prices 1155 --start 2024-01-01 --csv
73
+ bursakit dividends MAYBANK
74
+ bursakit listings --csv --out listings.csv
75
+ bursakit opr --start 2015-01-01
76
+ bursakit fx USD --start 2024-01-01 --csv
77
+ bursakit resolve maybank
78
+ bursakit cache info
79
+ ```
80
+
81
+ ## Schemas
82
+
83
+ Column names and dtypes are the same whichever source answered. Dates are timezone-naive
84
+ Malaysian calendar dates, the index is sorted and unique, money is in MYR.
85
+
86
+ | Function | Index | Columns |
87
+ | --- | --- | --- |
88
+ | `prices` | `date` | `open`, `high`, `low`, `close` (float64), `volume` (int64) |
89
+ | `dividends` | `date` (ex-date) | `amount` (float64, MYR per share) |
90
+ | `listings` | `code` (string) | `name`, `company`, `sector`, `market` (string) |
91
+ | `macro.opr` | `date` (decision date) | `rate`, `change` (float64, percent) |
92
+ | `macro.fx` | `date` | `buy`, `sell`, `mid` (float64, MYR per 1 unit of the currency) |
93
+
94
+ Known gaps: `market` is empty and `sector` uses Yahoo's sector names. Bursa's own
95
+ classification is only available from Bursa, whose terms forbid storing its website content
96
+ without written consent. Prices and dividends are adjusted for
97
+ splits and bonus issues by the source.
98
+
99
+ ## Errors
100
+
101
+ ```python
102
+ from bursakit import TickerNotFound, SourceUnavailable, RateLimited
103
+
104
+ try:
105
+ bk.prices("NOTAREALCO")
106
+ except TickerNotFound as exc:
107
+ print(exc.suggestions)
108
+ ```
109
+
110
+ | Error | Meaning |
111
+ | --- | --- |
112
+ | `TickerNotFound` | No Bursa listing matches. `.suggestions` holds near matches. |
113
+ | `SourceUnavailable` | Every source for that data type failed. `.causes` lists each failure. |
114
+ | `RateLimited` | A source asked us to slow down. Subclass of `SourceUnavailable`; `.retry_after` in seconds. |
115
+
116
+ A source that changes the shape of its response is rejected by the schema check and the next
117
+ source is tried. Nothing unvalidated is written to the cache.
118
+
119
+ A price day with a missing price or volume is dropped and the rest of the range is returned.
120
+ Each dropped day is logged as a warning on the `bursakit` logger.
121
+
122
+ ## Sources
123
+
124
+ | Data | Source order | Terms |
125
+ | --- | --- | --- |
126
+ | prices, dividends, listings, name lookup | Yahoo Finance through `yfinance` | Personal, non-commercial use; no redistribution |
127
+ | `macro.opr` | Bank Negara Malaysia Open API | Free, commercial use and redistribution allowed with credit |
128
+ | `macro.fx` | data.gov.my Open API, then Bank Negara Malaysia Open API | Same as BNM; data.gov.my is CC BY 4.0 |
129
+
130
+ **Yahoo data is for your own use.** Yahoo's terms do not allow automated collection, commercial
131
+ use or redistribution without Yahoo's written permission, and `yfinance` is unofficial. Do not
132
+ publish, sell or serve Yahoo-sourced prices, dividends or listings to others.
133
+
134
+ BNM and data.gov.my data can be shared and used commercially if you credit it: "Source: Bank
135
+ Negara Malaysia" with a link to the BNM dataset terms. `df.attrs` carries both.
136
+ See [docs/source-terms.md](https://github.com/MaosterM/bursakit/blob/main/docs/source-terms.md) for the clauses behind this table.
137
+
138
+ Requests to one source are spaced out. data.gov.my allows 4 requests a minute, so a second
139
+ request within 15 seconds waits. A wait of 5 seconds or more is logged as a warning on the
140
+ `bursakit` logger; `logging.getLogger("bursakit").setLevel("ERROR")` silences it.
141
+ See [docs/spike-go-no-go.md](https://github.com/MaosterM/bursakit/blob/main/docs/spike-go-no-go.md) for what was verified.
142
+
143
+ ## Cache
144
+
145
+ SQLite file under `%LOCALAPPDATA%\bursakit\Cache` on Windows or `~/.cache/bursakit` elsewhere.
146
+ Set `BURSAKIT_CACHE_DIR` to move it.
147
+
148
+ - Price, FX and OPR rows dated before today are kept permanently. Only the missing tail is fetched.
149
+ - Today's rows expire: 15 minutes for prices, 6 hours for FX and OPR.
150
+ - Dividends expire after 24 hours, listings after 7 days, name lookups after 30 days.
151
+ - Each price refresh overlaps the stored history by a week. If the overlap no longer matches
152
+ (a split or bonus issue), the ticker's history is refetched.
153
+ - `refresh=True` replaces what is stored for that ticker or series with the requested range.
154
+ The stored rows are removed only after the new fetch succeeds, so a failed refresh loses nothing.
155
+
156
+ ## Development
157
+
158
+ ```bash
159
+ git clone https://github.com/MaosterM/bursakit
160
+ cd bursakit
161
+ pip install -e ".[dev]"
162
+ pytest # offline, replays recorded responses
163
+ ruff check .
164
+ mypy
165
+ ```
166
+
167
+ Tests block network access. `python tests/record_fixtures.py` re-records the fixtures from
168
+ the live sources.
169
+
170
+ `pytest tests_live` asks the real sources for a little data and checks the answers still fit
171
+ the schemas. It needs network access and is not part of plain `pytest`. A GitHub Actions
172
+ workflow runs it every night; a failure there means a source changed or is down. A test is
173
+ skipped, not failed, when a source rate limits the machine running it.
@@ -0,0 +1,78 @@
1
+ """bursakit: Bursa Malaysia stock data and Malaysian macro series as DataFrames.
2
+
3
+ Every public function follows the same path: check the cache; on a miss ask
4
+ the router, which tries each source in order; validate the answer against the
5
+ schema; store it; return it.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from datetime import timedelta
11
+
12
+ import pandas as pd
13
+
14
+ from . import _util, cache, macro, router
15
+ from ._util import DateLike
16
+ from .errors import BursakitError, RateLimited, SchemaError, SourceUnavailable, TickerNotFound
17
+ from .tickers import Ticker, resolve
18
+
19
+ __version__ = "0.1.1"
20
+
21
+ __all__ = [
22
+ "BursakitError",
23
+ "RateLimited",
24
+ "SchemaError",
25
+ "SourceUnavailable",
26
+ "Ticker",
27
+ "TickerNotFound",
28
+ "__version__",
29
+ "cache",
30
+ "dividends",
31
+ "listings",
32
+ "macro",
33
+ "prices",
34
+ "resolve",
35
+ ]
36
+
37
+
38
+ def prices(
39
+ ticker: str | int | Ticker,
40
+ start: DateLike | None = None,
41
+ end: DateLike | None = None,
42
+ *,
43
+ refresh: bool = False,
44
+ ) -> pd.DataFrame:
45
+ """Daily open, high, low, close and volume for a Bursa-listed stock.
46
+
47
+ ``ticker`` may be a stock code (``1155``), a ``.KL`` symbol or a stock name
48
+ (``"MAYBANK"``). ``start`` and ``end`` are inclusive; the default is the
49
+ last 365 days. Prices are in MYR, adjusted for splits and bonus issues.
50
+ """
51
+ resolved = resolve(ticker)
52
+ first, last = _util.span(start, end, default=timedelta(days=365))
53
+ df, source = cache.series(
54
+ "prices",
55
+ resolved.code,
56
+ first,
57
+ last,
58
+ lambda s, e: router.fetch("prices", resolved, s, e),
59
+ verify="close",
60
+ overlap=7,
61
+ refresh=refresh,
62
+ )
63
+ return _util.tag(df, "prices", source, ticker=resolved.code)
64
+
65
+
66
+ def dividends(ticker: str | int | Ticker, *, refresh: bool = False) -> pd.DataFrame:
67
+ """Dividend history: MYR per share, indexed by ex-date."""
68
+ resolved = resolve(ticker)
69
+ df, source = cache.frame(
70
+ "dividends", resolved.code, lambda: router.fetch("dividends", resolved), refresh=refresh
71
+ )
72
+ return _util.tag(df, "dividends", source, ticker=resolved.code)
73
+
74
+
75
+ def listings(*, refresh: bool = False) -> pd.DataFrame:
76
+ """Companies listed on Bursa Malaysia: stock code, name, company, sector, market."""
77
+ df, source = cache.frame("listings", "all", lambda: router.fetch("listings"), refresh=refresh)
78
+ return _util.tag(df, "listings", source)
@@ -0,0 +1,64 @@
1
+ """Date helpers shared across the package."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from datetime import date, datetime, timedelta, timezone
6
+
7
+ import pandas as pd
8
+
9
+ #: Malaysia Time. UTC+8 all year, so no tz database is needed.
10
+ MYT = timezone(timedelta(hours=8), "MYT")
11
+
12
+ DateLike = str | date | datetime | pd.Timestamp
13
+
14
+
15
+ def today() -> date:
16
+ """Today's calendar date in Malaysia."""
17
+ return datetime.now(MYT).date()
18
+
19
+
20
+ def span(start: DateLike | None, end: DateLike | None, *, default: timedelta) -> tuple[date, date]:
21
+ """An inclusive date range: ``end`` defaults to today, ``start`` to ``end - default``."""
22
+ last = to_date(end) if end is not None else today()
23
+ first = to_date(start) if start is not None else last - default
24
+ if first > last:
25
+ raise ValueError(f"start {first} is after end {last}")
26
+ return first, last
27
+
28
+
29
+ def tag(df: pd.DataFrame, kind: str, source: str, **extra: str) -> pd.DataFrame:
30
+ """Record where a result came from in ``df.attrs``."""
31
+ from . import router
32
+
33
+ attrs: dict[str, str] = {"kind": kind}
34
+ attrs.update(extra)
35
+ attrs.update(
36
+ currency="MYR",
37
+ source=source,
38
+ attribution=router.attribution(source),
39
+ terms=router.terms(source),
40
+ )
41
+ df.attrs.clear()
42
+ df.attrs.update(attrs)
43
+ return df
44
+
45
+
46
+ def to_date(value: DateLike) -> date:
47
+ """Turn a string, date, datetime or Timestamp into a plain date."""
48
+ if isinstance(value, datetime): # also covers pd.Timestamp
49
+ return value.date()
50
+ if isinstance(value, date):
51
+ return value
52
+ if isinstance(value, str):
53
+ try:
54
+ return date.fromisoformat(value.strip())
55
+ except ValueError:
56
+ pass
57
+ try:
58
+ parsed = pd.Timestamp(value)
59
+ except (ValueError, TypeError) as exc:
60
+ raise ValueError(f"not a date: {value!r}") from exc
61
+ if pd.isna(parsed):
62
+ raise ValueError(f"not a date: {value!r}")
63
+ return parsed.date()
64
+ raise TypeError(f"expected a date or ISO date string, got {type(value).__name__}")