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.
- bursakit-0.1.1/.gitignore +11 -0
- bursakit-0.1.1/CHANGELOG.md +45 -0
- bursakit-0.1.1/LICENSE +21 -0
- bursakit-0.1.1/PKG-INFO +206 -0
- bursakit-0.1.1/README.md +173 -0
- bursakit-0.1.1/bursakit/__init__.py +78 -0
- bursakit-0.1.1/bursakit/_util.py +64 -0
- bursakit-0.1.1/bursakit/cache.py +382 -0
- bursakit-0.1.1/bursakit/cli.py +114 -0
- bursakit-0.1.1/bursakit/errors.py +69 -0
- bursakit-0.1.1/bursakit/macro.py +59 -0
- bursakit-0.1.1/bursakit/policy.py +197 -0
- bursakit-0.1.1/bursakit/py.typed +0 -0
- bursakit-0.1.1/bursakit/router.py +116 -0
- bursakit-0.1.1/bursakit/schema.py +195 -0
- bursakit-0.1.1/bursakit/sources/__init__.py +8 -0
- bursakit-0.1.1/bursakit/sources/_yf.py +97 -0
- bursakit-0.1.1/bursakit/sources/base.py +53 -0
- bursakit-0.1.1/bursakit/sources/bnm.py +107 -0
- bursakit-0.1.1/bursakit/sources/datagovmy.py +63 -0
- bursakit-0.1.1/bursakit/sources/yahoo.py +164 -0
- bursakit-0.1.1/bursakit/tickers.py +77 -0
- bursakit-0.1.1/docs/img/opr-usdmyr.png +0 -0
- bursakit-0.1.1/docs/source-terms.md +92 -0
- bursakit-0.1.1/docs/spike-go-no-go.md +54 -0
- bursakit-0.1.1/pyproject.toml +84 -0
- bursakit-0.1.1/tests/__init__.py +0 -0
- bursakit-0.1.1/tests/conftest.py +45 -0
- bursakit-0.1.1/tests/fixtures/README.md +14 -0
- 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
- 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
- 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
- bursakit-0.1.1/tests/fixtures/http/api_bnm_gov_my_public_opr_year_2023.json +4 -0
- bursakit-0.1.1/tests/fixtures/http/api_bnm_gov_my_public_opr_year_2024.json +4 -0
- 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
- 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
- bursakit-0.1.1/tests/fixtures/http/index.json +9 -0
- bursakit-0.1.1/tests/fixtures/yahoo/history_1155.KL.json +1 -0
- bursakit-0.1.1/tests/fixtures/yahoo/screen.json +2420 -0
- bursakit-0.1.1/tests/fixtures/yahoo/search_MAYBANK.json +71 -0
- bursakit-0.1.1/tests/fixtures/yahoo/search_NOTAREALCO.json +1 -0
- bursakit-0.1.1/tests/fixtures/yahoo/search_PUBLIC.json +82 -0
- bursakit-0.1.1/tests/fixtures/yahoo/search_TENAGA.json +67 -0
- bursakit-0.1.1/tests/record_fixtures.py +96 -0
- bursakit-0.1.1/tests/replay.py +85 -0
- bursakit-0.1.1/tests/test_api.py +190 -0
- bursakit-0.1.1/tests/test_cache.py +319 -0
- bursakit-0.1.1/tests/test_cli.py +76 -0
- bursakit-0.1.1/tests/test_package.py +11 -0
- bursakit-0.1.1/tests/test_policy.py +177 -0
- bursakit-0.1.1/tests/test_router.py +118 -0
- bursakit-0.1.1/tests/test_schema.py +105 -0
- bursakit-0.1.1/tests/test_sources.py +290 -0
- bursakit-0.1.1/tests/test_tickers.py +76 -0
- bursakit-0.1.1/tests_live/__init__.py +0 -0
- bursakit-0.1.1/tests_live/conftest.py +40 -0
- bursakit-0.1.1/tests_live/test_live.py +126 -0
|
@@ -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.
|
bursakit-0.1.1/PKG-INFO
ADDED
|
@@ -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
|
+
[](https://pypi.org/project/bursakit/)
|
|
37
|
+
[](https://pypi.org/project/bursakit/)
|
|
38
|
+
[](https://github.com/MaosterM/bursakit/actions/workflows/ci.yml)
|
|
39
|
+
[](https://github.com/MaosterM/bursakit/actions/workflows/live.yml)
|
|
40
|
+
[](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
|
+

|
|
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.
|
bursakit-0.1.1/README.md
ADDED
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
# bursakit
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/bursakit/)
|
|
4
|
+
[](https://pypi.org/project/bursakit/)
|
|
5
|
+
[](https://github.com/MaosterM/bursakit/actions/workflows/ci.yml)
|
|
6
|
+
[](https://github.com/MaosterM/bursakit/actions/workflows/live.yml)
|
|
7
|
+
[](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
|
+

|
|
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__}")
|