briskapi 0.2.0__py3-none-any.whl

briskapi/timing.py

@@ -0,0 +1,72 @@
+"""Timing-only statistics for sessions whose market data can't be shared (SBI BRiSK)."""
+from __future__ import annotations
+
+import datetime as dt
+from importlib.metadata import PackageNotFoundError, version
+
+from briskapi._recording import JST
+from briskapi.schema import MIN_TIMING_FRAMES, QUANTILES, TIMING_BOUNDS, TIMING_SCHEMA, validate_timing
+
+MAX_SAMPLES = 1_000_000
+STALL_MS = 1000
+
+
+def _client_version():
+    try:
+        return version('briskapi')
+    except PackageNotFoundError:  # pragma: no cover - running from an uninstalled checkout
+        return '0.0.0'
+
+
+def _distribution(values, low, high):
+    ordered = sorted(min(max(v, low), high) for v in values)
+    pick = lambda q: ordered[min(len(ordered) - 1, int(q * len(ordered)))]
+    return {name: round(value, 3) for name, value in zip(QUANTILES, (pick(.5), pick(.9), pick(.99), ordered[-1]))}
+
+
+class TimingStats:
+    """Accumulates per-frame decode time, data age at receipt and frame spacing.
+
+    Only these local measurements are kept; prices, quantities and codes are not.
+    """
+
+    def __init__(self, source):
+        self.source = source
+        self.trading_date = None
+        self.frames = self.stalls = 0
+        self.first = self.last = None
+        self.decode, self.age, self.gaps = [], [], []
+        self._midnight_ms = None
+
+    def add(self, batch):
+        if batch['type'] == 'bootstrap':
+            self.trading_date = batch['trading_date']
+            day = dt.datetime.strptime(self.trading_date, '%Y%m%d').replace(tzinfo=JST)
+            self._midnight_ms = day.timestamp() * 1000
+            return
+        received = batch.get('received_unix_ms')
+        if batch['type'] != 'quotes' or received is None or self.frames >= MAX_SAMPLES:
+            return
+        self.frames += 1
+        if self.last is not None:
+            gap = received - self.last
+            self.gaps.append(gap)
+            self.stalls += gap > STALL_MS
+        self.first = self.first if self.first is not None else received
+        self.last = received
+        self.decode.append(batch.get('decode_ns', 0) / 1e6)
+        # Age of the feed's own clock at local receipt; only as accurate as both clocks.
+        self.age.append(received - (self._midnight_ms + batch['source_time_us'] / 1000))
+
+    def report(self, contributor, license):
+        """The shareable report, or None when the session was too short to say anything."""
+        if self.trading_date is None or self.frames < MIN_TIMING_FRAMES:
+            return None
+        minute = lambda ms: dt.datetime.fromtimestamp(ms / 1000, JST).strftime('%H:%M')
+        report = dict(schema=TIMING_SCHEMA, source=self.source, trading_date=self.trading_date,
+                      first_minute=minute(self.first), last_minute=minute(self.last), frames=self.frames,
+                      stalls=self.stalls, client_version=_client_version(), contributor=contributor, license=license,
+                      decode_ms=_distribution(self.decode, *TIMING_BOUNDS['decode_ms']),
+                      source_age_ms=_distribution(self.age, *TIMING_BOUNDS['source_age_ms']),
+                      interarrival_ms=_distribution(self.gaps or [0], *TIMING_BOUNDS['interarrival_ms']))
+        return validate_timing(report)

briskapi-0.2.0.dist-info/METADATA

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: briskapi
+Version: 0.2.0
+Summary: Unofficial Python API, live feed and shared archive for BRiSK auction data
+License-Expression: MIT
+Project-URL: Source, https://github.com/honvl/BRiSKapi
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: boto3<2,>=1.41
+Provides-Extra: pandas
+Requires-Dist: pandas>=2; extra == "pandas"
+Dynamic: license-file
+
+# briskapi
+
+[English](README.md) | [日本語](README.ja.md)
+
+An unofficial, pybrisk-style Python API and `brisk` command line for BRiSK auction
+data. Consume a live feed, query recordings at any point in time, pull shared
+recordings from a public archive, and use SBI BRiSK with your own account. This
+is an independent project, not affiliated with or endorsed by BRiSK, Tachibana,
+SBI, TSE or JPX.
+
+> **Data sources:**
+> - **No account needed:** the public BRiSK Next demo of 27 September 2021 (one
+>   pre-open snapshot and the first three minutes after the open), replayed at
+>   its recorded pace. This is not live market data.
+> - **With an SBI Securities BRiSK subscription:** SBI BRiSK market data (candles,
+>   margin, alerts, schedule, watchlist) and an experimental live feed.
+
+## Install
+
+Python 3.12+. Live feeds and recording also need Node 22+, because BRiSK's own
+decoder is a WebAssembly module that runs under Node.
+
+```sh
+pip install 'briskapi[pandas]'      # `import briskapi` and the `brisk` command
+```
+
+BRiSK's decoder and demo data are downloaded at runtime; the package doesn't
+include them. Optional prebuilt Rust tools (`brisk_quote_ingest`,
+`brisk_recording`) for Linux, macOS and Windows are attached to each
+[GitHub release](https://github.com/honvl/BRiSKapi/releases). To work from source,
+clone the repository and run `pip install -e '.[pandas]'`.
+
+## Live feed
+
+```python
+import briskapi
+
+feed = briskapi.connect(web=True, codes=["7203", "6758"])   # returns once initial state is in
+toyota = briskapi.Ticker("7203")
+toyota.quote()        # current quote, updated as each frame arrives
+toyota.auction()      # indicative price/volume and market-order imbalance
+
+feed.on_quote(lambda q: print(q["code"], q["indicative_price"]), codes="6758")
+for q in feed.quotes("7203"):       # one item per update; ends with the session
+    if q["last_price"]:
+        print("opened at", q["last_price"], q["time"])
+        break
+
+briskapi.Market().imbalances(top=10).to_pandas()
+feed.wait()           # or feed.close(); `with briskapi.connect(...) as feed:` also works
+```
+
+Options: `web=True` (fetch from the demo site) or `cache=DIR` (a local copy of
+the demo assets), `codes`, `speed` (`1` real time, `0` as fast as possible) and
+`history=True` (keep updates for `Ticker.history()`). Callbacks and iterators
+first receive each security's current quote, then every update in order. A slow
+consumer slows the feed instead of losing updates.
+
+## Recordings and the archive
+
+```python
+briskapi.recordings(source="historical_mock")   # published recordings; no AWS account needed
+briskapi.pull("archive/20210927/SHA256")       # download, verify, decode and cache; becomes the default
+briskapi.load("recordings/my-session")         # or a local recording (events.jsonl[.gz] or folder)
+briskapi.record("recordings/my-session", web=True)   # record the demo yourself
+
+briskapi.Ticker("7203").quote(at="08:59:59.99")               # state at any JST time
+briskapi.Ticker("7203").history(start="09:00", end="09:01")   # every update in a window
+briskapi.Market().snapshot(at="09:00:00").to_pandas()
+```
+
+## SBI BRiSK
+
+For SBI Securities customers with a BRiSK subscription. Log in on
+[sbi.brisk.jp](https://sbi.brisk.jp) in your browser, then pass its session
+cookies: copy them from DevTools, or use `pycookiecheat`'s
+`chrome_cookies("https://sbi.brisk.jp")`.
+
+```python
+from briskapi import sbi
+
+sbi.login(cookies={"session_bfaf77a2": "v2.local..."})   # remember=True saves them (owner-only file)
+toyota = briskapi.Ticker("7203")
+toyota.candles("5m").to_pandas()   # price bars: 5m (today), 1d, 1w or 1mo
+toyota.margin(days=30)             # margin balances and stock-lending fees
+market = briskapi.Market()
+market.turnover()     # turnover and shares outstanding, all stocks
+market.lists()        # NK225, recent IPOs, …
+market.events()       # basket orders, limit up/down, volume surges
+market.schedule()     # trading date, status and session times
+market.watchlist()    # your saved codes
+
+feed = sbi.connect(codes=["7203"])          # live (experimental)
+toyota.quote()                              # same calls as any feed
+```
+
+Results use the conventions below. Errors are `sbi.SessionExpiredError` (log in
+again), `briskapi.NotFoundError`, `sbi.RateLimitError` and `sbi.APIError`.
+Requests are limited to one per second.
+
+The live feed runs SBI's own decoder under Node, downloaded with your session;
+no browser is involved. It hasn't yet been validated against a live SBI session,
+so it fails with an explicit error rather than guessing. Please report what you
+see. Your cookies go only to sbi.brisk.jp, and SBI market data never leaves
+your computer. With sharing on, a session contributes only a timing summary (see
+below).
+
+## API reference
+
+| Call | Returns |
+| --- | --- |
+| `briskapi.connect(...)` | Live `Feed`; becomes the default source |
+| `Ticker(code).info()` | Name, lot size, tick type, base price and daily limits |
+| `Ticker(code).quote(at=None)` | Bid/ask, indicative price/volume, market-order and closing quantities, last trade |
+| `Ticker(code).auction(at=None)` | Indicative auction state with `market_order_imbalance` (market buy minus sell) |
+| `Ticker(code).history(start, end)` | Every update in order |
+| `Market().stocks()` | Master for every security |
+| `Market().snapshot(at=None)` | Every security's quote |
+| `Market().imbalances(at=None, top=None)` | Securities ranked by absolute market-order imbalance |
+| `Market().summary()` | Source, date, coverage and clock range |
+| `Feed.quotes(codes)` / `Feed.on_quote(fn, codes)` | Live updates as they arrive |
+| `briskapi.recordings()` / `.pull()` / `.load()` | Archive listing, verified download, local file |
+| `briskapi.record(output, web=True, ...)` | A recording of the demo, shared per your choice |
+| `briskapi.consent(...)` | Your sharing choice |
+| `Ticker(code).candles(interval)` / `.margin(days)` | SBI BRiSK price bars; margin balances and lending fees |
+| `Market().turnover()` / `.lists()` / `.events()` / `.schedule()` / `.watchlist()` | SBI BRiSK market data |
+| `briskapi.sbi.login()` / `.connect()` | SBI BRiSK session and live feed |
+
+Prices are yen floats, with `None` for the vendor's zero "unavailable" value.
+Times are JST `datetime`s on the trading date. Quantities are shares; side, flag
+and status codes are raw vendor values. `raw=True` returns vendor fields
+(`*_price10` in tenths of a yen, `*_us` in microseconds since JST midnight).
+Tabular results are lists of dicts with `.to_pandas()`. Errors are
+`briskapi.BriskError` and `briskapi.NotFoundError`. A whole-market query reads a
+recording once (about six seconds for the complete 420 MB demo).
+
+## Command line
+
+```sh
+brisk live --web --codes 7203,6758          # one JSON object per quote update (--raw for vendor fields)
+brisk live --sbi --codes 7203               # SBI BRiSK; cookies from BRISK_SBI_COOKIES (JSON)
+brisk record --web --output recordings/s1   # record a replay (shared if you agreed)
+brisk list --date 20210927 --source historical_mock
+brisk pull archive/20210927/SHA256 --output recordings/downloaded
+brisk consent [--accept | --revoke]         # show or change sharing
+brisk upload recordings/s1                  # retry sharing a recording
+```
+
+Each command has `--help`. `pull` verifies everything before writing and never
+overwrites an existing folder.
+
+## Sharing recordings
+
+The first time you record or start a demo live session from the command line,
+the tool shows what would be shared and asks once; Enter accepts. After that,
+every complete demo session is uploaded and published automatically. The Python
+API never asks: until you decide, sessions stay on your computer.
+
+- **SBI sessions share timing only:** percentiles of decode time, data age at
+  receipt and frame spacing, a stall count, the frame count, the trading date,
+  the first and last minute, and your alias and license. Never prices,
+  quantities or codes. `briskapi.Archive().timing()` lists everyone's reports.
+- **What a demo session shares:** the market data you recorded, local timing measurements
+  (including your computer's clock, which shows when you recorded), and a public
+  alias (random `anon-…` by default) and license. Your IP address is used only to
+  rate limit uploads.
+- **Visibility:** published recordings are public and permanent, and you cannot
+  delete them yourself. See [PRIVACY.md](PRIVACY.md).
+- **Opting out:** `brisk consent --revoke`, `BRISK_CONTRIBUTE=0`, or `--no-upload`
+  for one run.
+- **License:** accepting declares that you may redistribute the recordings under
+  the chosen data license (CC0-1.0 or CC-BY-4.0). This project's open-source
+  license gives no rights to vendor or exchange data. If you can't make that
+  declaration, turn sharing off.
+- Partial replays (`--limit-frames`) and sessions closed early are never shared.
+
+## More documentation
+
+- [ARCHITECTURE.md](ARCHITECTURE.md): how it works, data format, archive integrity and limits
+- [PRIVACY.md](PRIVACY.md): privacy policy
+- [CONTRIBUTING.md](CONTRIBUTING.md): development, tests and releases
+- [tools/brisk_mock/README.md](tools/brisk_mock/README.md): Rust collector, field definitions, timing and latency
+- [tools/brisk_mock/NAUTILUS_V2.md](tools/brisk_mock/NAUTILUS_V2.md): NautilusTrader v2 integration
+- [infra/README.md](infra/README.md): deploying your own archive
+- [THIRD_PARTY.md](THIRD_PARTY.md): decoder, data and pybrisk attribution
+
+Software is MIT licensed.

briskapi-0.2.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+briskapi/LICENSE-pybrisk.txt,sha256=GqZvm14wEnuBJvyaV_H_TaKkJ7KGw24HLTzjl140-KM,1067
+briskapi/__init__.py,sha256=Ct1l9f6a87WXOvHudgehcsVSIB--2rq63ytE2Znp60A,2718
+briskapi/__main__.py,sha256=s-7n5-jcsEeiHahAAEbAeAefMI4zNxPjzeAqmAGY0iI,38
+briskapi/_archive.py,sha256=_BwrBmlKxIa8JvDBoZugirTl_b28jrru-3_YbTguiDk,2680
+briskapi/_live.py,sha256=vinfopccNKO57O4PGdYWzwM8MO3kYR3-U0_TYxvBy_o,15976
+briskapi/_market.py,sha256=u2GHHwVzIpFjJVkA5aqU_BpmyWxF06AAbT5F4Q_e1R0,5799
+briskapi/_recording.py,sha256=Vzv1tzHos-_Xx9DZzTZzH-2FshslCpubxr_KTqiNT6Y,7412
+briskapi/archive.json,sha256=C21yu75dxUc8u1-QH7jqlUWbkOQ2t-K7fleRSXrbTt8,168
+briskapi/cli.py,sha256=8hf9rcKt6EKqRS2HJbD0eDG_mxNoIKZNGmoQwmFu6HU,18166
+briskapi/sbi.py,sha256=zN_ZHz6Fcb_fDkDtf4N30FZDMNE3p3vzu2C6UXZfqXU,11860
+briskapi/schema.py,sha256=tsyhhUt5qHmYm7RkOfk-OmOm_udFvzFlZ1U0EyxvDG8,19121
+briskapi/timing.py,sha256=KcbYMs_t9C81RICYw_W9MSPp9NMcyjws2kb6UF9mRZA,3239
+briskapi/decoder/assets.json,sha256=fdTbjIUQs_Cypz5mbxqA0y-Ek6EkAPf7mTsvTG_e4i4,1090
+briskapi/decoder/decoder.cjs,sha256=RS9Ygf-vHD4thGD-FiMuriM8iAZcUERco04HBd2J95U,13783
+briskapi/decoder/sbi.cjs,sha256=7RwexPlCQML2uG1_5tjMEXdn5eo1qlve0llZ3WPoBRk,8145
+briskapi/decoder/web.cjs,sha256=d91IZIuo_nB4dIlLYO3_iKXotUR41OPbUFGaWnlZS6w,1815
+briskapi/references/historical_mock.json,sha256=geCqUFVhOh97eUNcIPs094A5L-pDj4R343ZfezR1x8w,157185
+briskapi-0.2.0.dist-info/licenses/LICENSE,sha256=NUMKVN8YDNTxtVQykfNwr_bjYoa0YhIPlsXtw_Ka11g,1062
+briskapi-0.2.0.dist-info/METADATA,sha256=KDVQ04JKpqypYWa9A-srT4tj4xnR0gI5-6u5i4XYv5Q,9891
+briskapi-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+briskapi-0.2.0.dist-info/entry_points.txt,sha256=wylW3PTuLnIZJzCjgacu4i_SuEB692jv_XTXNITIFLQ,44
+briskapi-0.2.0.dist-info/top_level.txt,sha256=xw3G1yaZBJxHavgu2bMbd3Y-nxRnlmIBcH5yT4BdskA,9
+briskapi-0.2.0.dist-info/RECORD,,

briskapi-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

briskapi-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+brisk = briskapi.cli:main

briskapi-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 honvl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

briskapi-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+briskapi