twmarketdata 0.1.0__tar.gz

twmarketdata-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,147 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  sandbox-install:
+    # Proves the package installs from wheels alone, with no compiler and no
+    # system libraries, across supported Pythons and platforms.
+    name: install + offline tests (py${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.9", "3.11", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install from wheels only
+        # --only-binary=:all: fails the build if any dependency would need to be
+        # compiled from source, which is the sandbox constraint we must hold.
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --only-binary=:all: -e ".[test]"
+
+      - name: Offline test suite
+        # No network: the live suite is deselected.
+        run: python -m pytest -m "not live" -q
+
+      - name: Assert no compiled extensions shipped
+        shell: python
+        run: |
+          import pathlib, sys
+          bad = [
+              str(p)
+              for p in pathlib.Path("src/twmd").rglob("*")
+              if p.suffix in {".so", ".pyd", ".dylib", ".c", ".pyx"}
+          ]
+          if bad:
+              sys.exit("compiled artefacts found in package: " + ", ".join(bad))
+          print("pure Python: ok")
+
+  dependency-floor:
+    # requires-python is >=3.9 and pandas is >=1.5 to maximise the number of
+    # environments this installs into. A declared floor nobody tests is a guess,
+    # so this job pins the floor exactly and runs the suite against it.
+    name: declared dependency floor (py3.9)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.9"
+
+      - name: Install at the declared floor
+        # numpy<2 is required alongside pandas 1.5: pandas 1.5 wheels are built
+        # against the numpy 1.x C ABI and abort at import under numpy 2 with
+        # "numpy.dtype size changed". That is a pandas/numpy ABI constraint, not
+        # a twmd one — our code passes the full suite on pandas 1.5 — but the
+        # floor must be installed the way it actually works.
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --only-binary=:all: "pandas==1.5.0" "numpy<2" "httpx==0.27.0"
+          python -m pip install --only-binary=:all: --no-deps -e .
+          python -m pip install pytest respx
+
+      - name: Report resolved versions
+        run: |
+          python -c "import sys,pandas,numpy,httpx; print(f'py {sys.version.split()[0]} | pandas {pandas.__version__} | numpy {numpy.__version__} | httpx {httpx.__version__}')"
+
+      - name: Offline test suite at the floor
+        run: python -m pytest -m "not live" -q
+
+  live-keyfree:
+    # The zero-configuration promise: five sample tickers, no credentials.
+    # Needs egress, so it is a separate job from the sandbox install check.
+    name: live key-free acceptance
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[test]"
+
+      - name: Key-free acceptance against the live API
+        # TWMD_API_KEY is deliberately not set: this must pass with no credentials.
+        run: python -m pytest -m live -q
+
+  compliance:
+    # Positioning gate: this package is a data-access layer. Nothing in it may
+    # read as investment advice, a recommendation, or a directional claim.
+    name: compliance scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Scan for advisory or directional language
+        shell: bash
+        run: |
+          set -uo pipefail
+          # Deliberately blunt. A false positive is cheap to reword; a false
+          # negative ships advisory language. Do not loosen this to accommodate
+          # a phrasing — change the phrasing.
+          #
+          # Excluded on purpose: this file (it necessarily contains the terms it
+          # bans) and build/cache dirs. Everything else is in scope, including
+          # tests, comments and packaging metadata.
+          #
+          # Not banned, and why: "backtest" and "point-in-time" appear only
+          # inside a verbatim quote of the API's own survivorship_bias_warning;
+          # banning them would force us to misquote an upstream integrity
+          # caveat. "signal" is caught only in its advisory senses below.
+          PATTERN='\b(buy|sell|hold) (signal|recommendation|rating)|\brecommend(s|ed|ation|ations)?\b|\bstock (pick|tip)|\bshould (buy|sell|invest)|\bbullish\b|\bbearish\b|\blong/short\b|\bwin.?rate\b|\bprofit(able|ability)\b|\bguarantee|\boutperform|\bprice target|\b(alpha|trade|trading|entry|exit) signal|\btrading strategy|\bwill (rise|fall|go up|go down)|\bbeat the market|\b(under|over)valued\b|\brisk.adjusted\b|\bsharpe\b|\bmarket timing\b|\bscreen for\b|\bedge over\b|\binvestment advice\b'
+          # A disclaimer must be able to name what it disclaims. So matches are
+          # filtered through a second pass that drops lines carrying an explicit
+          # negation — "does not generate recommendations" is the positioning
+          # working, not failing. Anything asserted affirmatively still fails.
+          NEGATED='\b(no|not|never|nothing|neither|nor|without|deliberately not|does not|do not|is not|are not|may not|should not|free of)\b'
+
+          HITS=$(grep -rEIn \
+                   --exclude-dir=.git --exclude-dir=.venv --exclude-dir=.pytest_cache \
+                   --exclude-dir=__pycache__ --exclude-dir=build --exclude-dir=dist \
+                   --exclude=ci.yml \
+                   -i "$PATTERN" . | grep -vEi "$NEGATED" || true)
+
+          if [ -n "$HITS" ]; then
+            echo "$HITS"
+            echo "::error::Advisory or directional language found. This package is data access only."
+            exit 1
+          fi
+          echo "no advisory language: ok"

twmarketdata-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.coverage
+htmlcov/
+.DS_Store
+.env

twmarketdata-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TW Market Data
+
+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.

twmarketdata-0.1.0/PKG-INFO

@@ -0,0 +1,319 @@
+Metadata-Version: 2.4
+Name: twmarketdata
+Version: 0.1.0
+Summary: Data-access client for the TW Market Data API. Retrieval only, for research and education.
+Project-URL: Homepage, https://twmarketdata.com
+Project-URL: Documentation, https://api.twmarketdata.com/openapi.json
+Author: TW Market Data
+License: MIT License
+        
+        Copyright (c) 2026 TW Market Data
+        
+        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.
+License-File: LICENSE
+Keywords: api-client,dataset,market-data,research,taiwan
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pandas>=1.5
+Provides-Extra: test
+Requires-Dist: pytest>=7.4; extra == 'test'
+Requires-Dist: respx>=0.21; extra == 'test'
+Description-Content-Type: text/markdown
+
+# twmd
+
+Python data-access client for the [TW Market Data](https://twmarketdata.com) API.
+
+`twmd` retrieves published datasets over HTTP and returns them as pandas
+DataFrames. It is a transport layer for data retrieval, intended for research
+and educational use. It fetches records as the API publishes them and performs
+no analysis, scoring, ranking, or interpretation of any kind. Deciding what the
+data means, and what if anything to do about it, is entirely the caller's own
+work and responsibility.
+
+Responses carry the API's own `lineage.not_investment_advice` flag; this client
+preserves it unmodified.
+
+## Install
+
+```bash
+pip install twmarketdata
+```
+
+The distribution is named `twmarketdata`; the import package is `twmd`:
+
+```python
+import twmd
+```
+
+Pure Python. Dependencies are `httpx` and `pandas` — no compiled extensions, no
+system libraries, installable in a restricted sandbox.
+
+Requires Python 3.9 or newer. The floors are deliberately low (`pandas>=1.5`,
+`httpx>=0.27`) so this installs into existing environments without forcing an
+upgrade, and CI runs the full suite pinned to exactly those floors so they stay
+honest rather than aspirational.
+
+One caveat that is not ours to fix: pandas 1.5 wheels are built against the
+numpy 1.x C ABI and fail at import under numpy 2 with `numpy.dtype size
+changed`. If you are pinned to pandas 1.x, pin `numpy<2` alongside it. Anything
+from pandas 2.2.2 onward works with numpy 2 unconstrained.
+
+## Quick start — no API key needed
+
+Five sample tickers are served without credentials on selected datasets, so
+this runs with zero configuration:
+
+```python
+from twmd import Client
+
+client = Client()
+df = client.get_dataset("twse-daily-price", symbol="2330", limit=5)
+
+print(df[["date", "open", "high", "low", "close", "volume_shares"]])
+print(df.attrs["data_as_of"])       # data freshness date
+print(df.attrs["lineage"])          # provider, source endpoints, source table
+```
+
+## Authentication
+
+Set your key in the environment; it is never written to disk or logged:
+
+```bash
+export TWMD_API_KEY="sk_live_..."
+```
+
+`Client()` picks it up automatically. You may also pass `Client(api_key=...)`
+explicitly. With no key set, the client runs in key-free mode and reaches the
+datasets listed below.
+
+## Key-free access matrix
+
+Key-free access is scoped **per dataset**, not globally per ticker. The same
+ticker that is served on one dataset may require a key on another. Measured
+against the live API on 2026-07-21:
+
+| Tier | Datasets | Tickers served without a key |
+| --- | --- | --- |
+| Open | `security-master`, `market-index` | any |
+| Sample | `twse-daily-price`, `tpex-daily-price`, `monthly-revenue` | `2330`, `2317`, `2454`, `0050`, `2603` only |
+| Key required | everything else, including `institutional-flow`, `market-prices`, `financial-metrics`, `income-statement`, `balance-sheet` | none |
+
+Check before requesting:
+
+```python
+from twmd import is_key_free
+
+is_key_free("twse-daily-price", "2330")     # True
+is_key_free("twse-daily-price", "1101")     # False — outside the sample set
+is_key_free("security-master", "1101")      # True — open dataset
+is_key_free("institutional-flow", "2330")   # False — key required
+```
+
+Datasets not in the table are treated as key-required, which is the safe
+default. The client never blocks a request on this basis — it only uses the
+matrix to explain a 401 after the fact.
+
+## DataFrames and metadata
+
+Records become rows. Everything else in the response envelope is preserved on
+`df.attrs`.
+
+The API uses **two envelope shapes**, and `twmd` handles both transparently:
+
+```python
+# rows / count — twse-daily-price, tpex-daily-price, monthly-revenue
+df.attrs["dataset"]       # "twse_daily_price"
+df.attrs["count"]         # record count
+df.attrs["data_as_of"]    # data freshness date
+df.attrs["source_role"]   # e.g. "official_twse"
+df.attrs["lineage"]       # provider, official_source, source_endpoints, table
+df.attrs["meta"]          # last_trading_day, market_status
+
+# items / row_count — security-master, market-index
+df.attrs["dataset_id"]                  # "security-master"
+df.attrs["row_count"]                   # record count
+df.attrs["as_of_date"]                  # snapshot date
+df.attrs["survivorship_bias_warning"]   # integrity caveat raised by the API
+```
+
+Envelope contents vary by dataset — `monthly-revenue` sends only `dataset`,
+`rows` and `count` — so read `attrs` defensively.
+
+Records in the `items` variant contain nested objects (`security_identity`,
+`market_identity`, `index_level`). These stay as dict-valued columns rather than
+being flattened, so a DataFrame reflects what the API actually sent. Expand one
+when you want to:
+
+```python
+import pandas as pd
+identity = pd.json_normalize(df["security_identity"])
+```
+
+Note that `security-master` carries a `survivorship_bias_warning` stating the
+current master is not point-in-time complete. It is surfaced on `attrs`
+unmodified; check it before using that dataset for historical work.
+
+## Errors
+
+```python
+from twmd import Client, TwmdAuthError, TwmdPaymentRequired
+
+try:
+    df = client.get_dataset("institutional-flow", symbol="2330")
+except TwmdAuthError as exc:
+    print(exc.error_code)   # "missing_api_key" or "invalid_api_key"
+    print(exc.body)         # decoded response body, verbatim
+```
+
+Every `TwmdAPIError` subclass — every row in the table below except the last —
+exposes `.status_code`, `.body` (decoded body, unmodified), `.text` and
+`.error_code`. `TwmdTransportError` and `TwmdConfigError` derive from `TwmdError`
+directly and carry none of those, since no response was received.
+
+| Status | Exception | Retried |
+| --- | --- | --- |
+| 401 | `TwmdAuthError` | no |
+| 402 | `TwmdPaymentRequired` | no |
+| 404 | `TwmdNotFoundError` | no |
+| 422 | `TwmdValidationError` | no |
+| 429 | `TwmdRateLimitError` | yes |
+| 5xx | `TwmdServerError` | yes |
+| network failure | `TwmdTransportError` | yes |
+
+Retries use exponential backoff with jitter. A `Retry-After` header — in either
+RFC 7231 form, delta-seconds or HTTP-date — overrides that and is honoured
+exactly, with no jitter and no shortening, since retrying sooner than the server
+permitted is worse than waiting too long. If it asks for more than
+`RETRY_AFTER_MAX` (120s) the client stops and raises the server's error rather
+than blocking for minutes.
+
+401 messages are annotated with the key-free status of the dataset and ticker
+you asked for, so "I forgot my key" is distinguishable from "that ticker is not
+in the sample set".
+
+### On 402
+
+**No 402 response has been observed from this API.** The probe on 2026-07-21
+found zero endpoints declaring 402 in the published OpenAPI document, and
+unauthenticated requests to key-gated datasets return 401 `missing_api_key`.
+`TwmdPaymentRequired` exists as a documented extension point: if the API does
+return 402 — the untested path is a *valid but unentitled* key, which requires
+live credentials to exercise — the full decoded body is preserved verbatim on
+`.body` and reaches your code intact. The client deliberately does not model or
+require any field layout inside it, since no 402 body exists to model.
+
+```python
+except TwmdPaymentRequired as exc:
+    handle_payment_required(exc.body)   # whole body, nothing dropped
+```
+
+## Source attribution
+
+Pass `source` to mark every request with the integration that produced it, so
+the publisher can attribute traffic:
+
+```python
+client = Client(source="ecosys/tradingagents")
+```
+
+It is attached as a `source` query parameter on every request. A per-call
+`source=` on `get_dataset` overrides the client-wide value. It is an ordinary
+query parameter — it does not change the response, does not enter a data
+response's `request_context.filters`, and carries nothing about the user. Leave
+it unset to send nothing.
+
+## Pagination
+
+```python
+df = client.get_all("twse-daily-price", symbol="2330", limit=1000)
+
+for page in client.iter_pages("twse-daily-price", symbol="2330", limit=500):
+    process(page)
+```
+
+The API publishes no cursor: no `cursor` or `next_cursor` field appears in any
+response or in the OpenAPI document. Paging is `limit`/`offset`, and `offset`
+was measured to be **ignored** on the key-free endpoints — `offset=3` returned
+the same records as `offset=0`.
+
+So pagination here is defensive. It advances `offset` as documented, then stops
+when either a page comes back shorter than `limit`, or a page repeats the
+previous page's first record — the signature of a silently ignored `offset`.
+Against endpoints that ignore `offset` this yields exactly one page, which is
+the correct outcome rather than a failure. `max_pages` caps the loop.
+
+## `as_of`
+
+`get_dataset()` accepts an `as_of` argument and forwards it as a query
+parameter. **Its scope is narrow.** As measured on 2026-07-21:
+
+- `as_of` is declared on exactly four endpoints — `income-statement`,
+  `cash-flow-statement`, `balance-sheet`, `financials` — all of which require an
+  API key.
+- On every other endpoint it is not a declared parameter. The API silently
+  ignores unknown query parameters, returning 200 rather than 422, so passing
+  `as_of` there has no observable effect and raises no error.
+- Its behaviour on the four declared endpoints is **unverified** by this
+  project, which has no credentials to exercise them.
+
+Treat `as_of` as forwarded-but-unconfirmed rather than as a general
+point-in-time facility. The `data_as_of` field in responses is a data-freshness
+date and is a different thing.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest -m "not live"    # offline, no network
+pytest -m live          # hits the real API, key-free paths only
+```
+
+The live suite asserts a sample of the key-free matrix — seven dataset/ticker
+pairs — still matches what the API serves, so drift in those surfaces as a test
+failure. It is a tripwire, not full coverage: the five sample tickers are
+verified only against `twse-daily-price`, and three datasets listed as
+key-required are assumed rather than probed (see
+`access.PRESUMED_KEY_REQUIRED_DATASETS`, and `access.provenance()` to tell the
+two apart).
+
+## Scope
+
+This package retrieves data. It does not generate recommendations, forecasts,
+signals, valuations, or opinions about any security, and nothing it returns
+should be read as such. The data is provided for research and educational
+purposes; verify it against the original sources before relying on it. Use of
+the underlying API is governed by TW Market Data's own terms.
+
+## License
+
+MIT

twmarketdata-0.1.0/PYPI_PUBLISH_OWNER.md

@@ -0,0 +1,113 @@
+# PyPI 發布指令包 — `twmarketdata`（owner 執行）
+
+**核准**：owner 已核准 PyPI 發布（2026-07-21）。
+**發布名**：`twmarketdata`（PyPI 400 拒絕 `twmd`：與既有專案過於相似）。**import 名仍是 `twmd`**——零程式碼改動，使用者 `pip install twmarketdata` 後 `import twmd`。
+**原則**：以下全部 ⟦OWNER 執行⟧。帳號與 API token 為 owner 親辦憑證，不經終端/agent。**同一個先前建的 token 可續用**（account-scope）。
+**已驗**：agent 已改名後重新產出並驗證 artifacts（`python -m build` 成功、`twine check` 兩檔 PASSED、wheel 純 Python 無編譯物、含 LICENSE、import 名不變）。owner 只需憑證 + 上傳。
+
+---
+
+## 前置 A — PyPI 帳號（若已有，跳到前置 B）⟦OWNER⟧
+
+1. 註冊：**https://pypi.org/account/register/**
+2. 開啟 2FA（PyPI 現在強制）：帳號設定 → Two factor authentication
+3. （建議）先在 TestPyPI 也註冊一個，供試上傳：**https://test.pypi.org/account/register/**
+
+## 前置 B — API token ⟦OWNER⟧
+
+1. 開 **https://pypi.org/manage/account/token/**
+2. Add API token
+   - Token name：`twmarketdata-publish`
+   - Scope：首次發布選 **"Entire account"**（因為 `twmarketdata` 專案尚不存在，無法限定專案 scope）；首次上傳後可回來刪掉、改發一個 project-scoped token 給後續版本用。**先前為 `twmd` 建的 account-scope token 仍可直接用於本次上傳。**
+3. 複製 token（`pypi-...` 開頭，**只顯示一次**）
+
+> token 就是上傳憑證。不要貼進任何檔案或終端歷史。下方用互動式輸入或環境變數當場帶入。
+
+---
+
+## 名稱可用性檢查 ⟦OWNER，建議先做⟧
+
+`twmarketdata` 這名字在 PyPI 是否可用（前一次 `twmd` 被相似度規則擋下，已改此名）：
+```
+# 開瀏覽器看，404 = 可用
+open https://pypi.org/project/twmarketdata/
+```
+若這名字也被相似度規則擋（上傳時回 400）→ 回報 agent，再擇名（例如 `tw-market-data`），agent 同步改 `pyproject.toml` 的 `name`、README、§3 provider 的 `pip install` 指示後重建。
+
+---
+
+## 發布 ⟦OWNER 在終端執行⟧
+
+工作目錄與已驗 artifacts：
+```
+cd /Volumes/DEV_USB/Projects/twmd-python-client
+ls dist/
+#   twmarketdata-0.1.0-py3-none-any.whl
+#   twmarketdata-0.1.0.tar.gz
+```
+> 若 `dist/` 仍見舊的 `twmd-0.1.0.*`，先 `rm -rf dist/twmd-0.1.0.*`——只上傳 `twmarketdata-*`。
+
+### 選項 1（建議）：先上 TestPyPI 演練，確認無誤再上正式
+
+```
+# 用已建好的 .venv 的 twine（agent 已裝）
+.venv/bin/python -m twine upload --repository testpypi dist/*
+#   Username: __token__
+#   Password: <貼上 TestPyPI 的 API token>
+
+# 驗證 TestPyPI 能裝（乾淨環境）— 裝 twmarketdata、import twmd
+python3 -m venv /tmp/twmd-test && \
+  /tmp/twmd-test/bin/pip install --index-url https://test.pypi.org/simple/ \
+    --extra-index-url https://pypi.org/simple/ twmarketdata && \
+  /tmp/twmd-test/bin/python -c "import twmd; print(twmd.__version__)"
+```
+> `--extra-index-url` 讓依賴（httpx/pandas）從正式 PyPI 抓，因為 TestPyPI 未必有。
+
+### 選項 2 或演練後：上正式 PyPI
+
+```
+cd /Volumes/DEV_USB/Projects/twmd-python-client
+.venv/bin/python -m twine upload dist/*
+#   Username: __token__
+#   Password: <貼上正式 PyPI 的 API token>
+```
+
+若偏好環境變數（避免互動貼上）：
+```
+export TWINE_USERNAME=__token__
+export TWINE_PASSWORD=pypi-XXXX...        # 正式 token
+.venv/bin/python -m twine upload dist/*
+unset TWINE_PASSWORD                       # 用完清掉
+```
+
+---
+
+## 發布後確認 ⟦OWNER⟧
+
+```
+open https://pypi.org/project/twmarketdata/   # 頁面出現、README 店面正確
+# 從任意乾淨環境驗證公開可裝（裝 twmarketdata、import twmd）：
+python3 -m venv /tmp/twmd-live && \
+  /tmp/twmd-live/bin/pip install twmarketdata && \
+  /tmp/twmd-live/bin/python -c "import twmd; print('live:', twmd.__version__)"
+```
+
+回報 agent「twmarketdata 0.1.0 已上 PyPI」→ agent 更新 memory，並確認 §3 TA PR 的 `pip install twmarketdata` 前置已滿足。
+
+---
+
+## 重發／改版注意（記著）
+
+- PyPI **同一版本號不可覆蓋**。若發現需修，改 `pyproject.toml` 的 `version`（例如 `0.1.1`），重跑 `python -m build` 再上傳。
+- 若首次用 account-scoped token：上傳成功後到 token 頁刪它，改發 `twmd` project-scoped token 給後續版本，縮小憑證範圍。
+
+---
+
+## agent 已完成（owner 無需重做）
+
+- [x] `pyproject.toml` 元資料齊備（name/version/description/readme/license/requires-python）
+- [x] LICENSE 檔就位，打包進 wheel
+- [x] `python -m build` → wheel + sdist 成功
+- [x] `twine check dist/*` → 兩檔 PASSED
+- [x] wheel 內容驗證：純 Python、零編譯物、含 LICENSE、5 模組
+- [x] 依賴僅 httpx + pandas（純 pip、sandbox 友善）