settfex 0.2.1__tar.gz → 0.4.0__tar.gz

{settfex-0.2.1 → settfex-0.4.0}/.github/workflows/release.yml

@@ -141,7 +141,6 @@ jobs:
           path: dist/
 
       - name: Extract changelog section
-        id: changelog
         run: |
           VERSION="${{ needs.validate.outputs.version }}"
           python3 - "$VERSION" <<'PYEOF'
@@ -152,19 +151,14 @@ jobs:
           match = re.search(pattern, content, re.DOTALL)
           notes = match.group(1).strip() if match else f"Release v{version}"
           with open("release_notes.txt", "w") as f:
-              f.write(notes)
+              f.write(notes + "\n")
           PYEOF
-          {
-            echo 'notes<<CHANGELOG_EOF'
-            cat release_notes.txt
-            echo 'CHANGELOG_EOF'
-          } >> "$GITHUB_OUTPUT"
 
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
           name: "settfex v${{ needs.validate.outputs.version }}"
-          body: ${{ steps.changelog.outputs.notes }}
+          body_path: release_notes.txt
           prerelease: ${{ needs.validate.outputs.is_prerelease }}
           files: dist/*
           make_latest: ${{ needs.validate.outputs.is_prerelease == 'false' }}

{settfex-0.2.1 → settfex-0.4.0}/CHANGELOG.md

@@ -5,6 +5,48 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.4.0] - 2026-06-19
+
+### Added
+
+- **SET Earnings Call (Opportunity Day) service** (`get_earnings_calls`,
+  `get_earnings_calls_dataframe`, `EarningsCallService`, `EarningsCallItem`,
+  `EarningsCallResponse`, `EarningsCallDetail`, `FilterOption`): fetches the SET
+  "Earnings Call (OPPDAY)" calendar from the stateless opportunity-day backend
+  (`POST https://api.lcp.setgroup.or.th/api/v1/investor/search/archive`). Returns typed
+  Pydantic models with derived `company_name_clean` / `youtube_video_id` / `youtube_url`
+  fields, plus an optional pandas DataFrame (`to_dataframe()`) whose default columns are
+  `stock_name, company_name, earnings_call_date, video_clip_time, youtube_url`. Includes
+  bounded auto-pagination (`fetch_all_earnings_calls`), opt-in concurrent detail enrichment
+  (`enrich=True`), seven filter helpers, and a `*_raw` variant. This host needs no
+  cookies/Incapsula bypass, so it uses a plain sessionless fetcher. Not stock-scoped (not on
+  the `Stock` class). Adds the `docs/settfex/services/set/earnings_call.md` doc and the
+  `examples/set/12_earnings_call.ipynb` notebook.
+- **`AsyncDataFetcher` POST support**: `fetch()` / `fetch_json()` now accept keyword-only
+  `method="GET"` (default — fully backward compatible) and `json_body`. POST runs through the
+  standalone (sessionless) path and the same NaN-rejecting JSON decoder; POST via a persistent
+  session is intentionally unsupported (raises `NotImplementedError`).
+
+### Changed
+
+- pandas is now available as an optional `dataframe` extra
+  (`pip install "settfex[dataframe]"`); it is required only for the DataFrame convenience and
+  is imported lazily, so importing the library never requires pandas.
+
+## [0.3.0] - 2026-06-17
+
+### Added
+
+- **TFEX underlying-price service** (`get_underlying_price`, `TFEXUnderlyingPriceService`,
+  `UnderlyingPrice`): fetches the underlying instrument price for a TFEX series via
+  `GET /api/set/tfex/series/{symbol}/underlying-price`. For SET50 index options/futures the underlying
+  is the **SET50 index spot** — exposes last/prior/high/low, change, total volume/value, and P/E + P/BV.
+  Mirrors the existing TFEX service pattern (SessionManager/Incapsula bypass, NaN-rejecting hardened
+  parsing, `get_*` convenience function + `*_raw` variant); 100% module test coverage. Adds the
+  `verify_underlying_price.py` script and the `examples/tfex/03_underlying_price.ipynb` notebook.
+
 ## [0.2.1] - 2026-06-17
 
 Robustness and concurrency hardening release. No public API changes — function

{settfex-0.2.1 → settfex-0.4.0}/CONTRIBUTING.md

@@ -61,6 +61,12 @@ Detailed engineering guidelines live in [`.github/instructions/`](.github/instru
 4. Ensure the quality gate passes.
 5. Open a PR using the template and link any related issue.
 
+## Releasing
+
+Releases go through a single path: bump the version, update `CHANGELOG.md`, merge to `main`,
+then push a `vX.Y.Z` git tag. The tag triggers CI to publish to PyPI (via OIDC) and create the
+GitHub Release. See [`RELEASING.md`](RELEASING.md) for the exact steps and the one-time setup.
+
 ## Reporting security issues
 
 Please do **not** open public issues for vulnerabilities — see

{settfex-0.2.1 → settfex-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: settfex
-Version: 0.2.1
+Version: 0.4.0
 Summary: Async Python library for fetching real-time and historical data from the Stock Exchange of Thailand (SET) and Thailand Futures Exchange (TFEX)
 Project-URL: Homepage, https://github.com/lumduan/settfex
 Project-URL: Documentation, https://github.com/lumduan/settfex#readme
@@ -30,6 +30,8 @@ Requires-Dist: curl-cffi>=0.6.0
 Requires-Dist: diskcache>=5.6.0
 Requires-Dist: loguru>=0.7.0
 Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dataframe
+Requires-Dist: pandas>=2.0.0; extra == 'dataframe'
 Provides-Extra: examples
 Requires-Dist: jupyter>=1.0.0; extra == 'examples'
 Requires-Dist: matplotlib>=3.7.0; extra == 'examples'
@@ -122,6 +124,7 @@ Want to dig deeper? Check out our detailed guides:
 - **[Financial Service](docs/settfex/services/set/financial.md)** - Balance sheet, income statement, and cash flow data
 - **[Chart Quotation Service](docs/settfex/services/set/chart_quotation.md)** - Intraday and historical price chart data
 - **[Latest Historical Trading Service](docs/settfex/services/set/latest_historical_trading.md)** - Latest trading day summary with OHLCV and valuation metrics
+- **[Earnings Call (Opportunity Day) Service](docs/settfex/services/set/earnings_call.md)** - OPPDAY earnings-call calendar with YouTube links, as models or a DataFrame
 
 ### TFEX Services
 
@@ -418,6 +421,31 @@ print(f"Market Cap: {trading.market_cap:,.0f} THB")
 
 ---
 
+#### 🎤 Get Earnings Call (Opportunity Day) Calendar
+
+Fetch the SET Opportunity Day earnings-call calendar — symbol, company, date, clip duration,
+and a ready-to-use YouTube link — as typed models or a pandas DataFrame:
+
+```python
+from settfex.services.set import get_earnings_calls, get_earnings_calls_dataframe
+
+# Typed models
+response = await get_earnings_calls()
+for item in response.items[:5]:
+    print(item.symbol, item.company_name_clean, item.youtube_url)
+
+# …or straight to a DataFrame (requires: pip install "settfex[dataframe]")
+df = await get_earnings_calls_dataframe()
+# columns: stock_name, company_name, earnings_call_date, video_clip_time, youtube_url
+
+# Search one company, or filter by quarter/type
+hann = await get_earnings_calls(keyword="HANN")
+```
+
+**👉 [Learn more about the Earnings Call Service](docs/settfex/services/set/earnings_call.md)**
+
+---
+
 ### TFEX (Thailand Futures Exchange)
 
 #### 📋 Get TFEX Series List
@@ -609,6 +637,12 @@ stock_list = await get_stock_list()
 
 Great for debugging or monitoring in production. Default is ERROR level for clean output.
 
+## 📋 Changelog
+
+See **[CHANGELOG.md](CHANGELOG.md)** for the full, versioned release history (this project
+follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and
+[Semantic Versioning](https://semver.org/)).
+
 ## 🤝 Contributing
 
 We'd love your help making settfex better! Here's how:

{settfex-0.2.1 → settfex-0.4.0}/README.md

@@ -83,6 +83,7 @@ Want to dig deeper? Check out our detailed guides:
 - **[Financial Service](docs/settfex/services/set/financial.md)** - Balance sheet, income statement, and cash flow data
 - **[Chart Quotation Service](docs/settfex/services/set/chart_quotation.md)** - Intraday and historical price chart data
 - **[Latest Historical Trading Service](docs/settfex/services/set/latest_historical_trading.md)** - Latest trading day summary with OHLCV and valuation metrics
+- **[Earnings Call (Opportunity Day) Service](docs/settfex/services/set/earnings_call.md)** - OPPDAY earnings-call calendar with YouTube links, as models or a DataFrame
 
 ### TFEX Services
 
@@ -379,6 +380,31 @@ print(f"Market Cap: {trading.market_cap:,.0f} THB")
 
 ---
 
+#### 🎤 Get Earnings Call (Opportunity Day) Calendar
+
+Fetch the SET Opportunity Day earnings-call calendar — symbol, company, date, clip duration,
+and a ready-to-use YouTube link — as typed models or a pandas DataFrame:
+
+```python
+from settfex.services.set import get_earnings_calls, get_earnings_calls_dataframe
+
+# Typed models
+response = await get_earnings_calls()
+for item in response.items[:5]:
+    print(item.symbol, item.company_name_clean, item.youtube_url)
+
+# …or straight to a DataFrame (requires: pip install "settfex[dataframe]")
+df = await get_earnings_calls_dataframe()
+# columns: stock_name, company_name, earnings_call_date, video_clip_time, youtube_url
+
+# Search one company, or filter by quarter/type
+hann = await get_earnings_calls(keyword="HANN")
+```
+
+**👉 [Learn more about the Earnings Call Service](docs/settfex/services/set/earnings_call.md)**
+
+---
+
 ### TFEX (Thailand Futures Exchange)
 
 #### 📋 Get TFEX Series List
@@ -570,6 +596,12 @@ stock_list = await get_stock_list()
 
 Great for debugging or monitoring in production. Default is ERROR level for clean output.
 
+## 📋 Changelog
+
+See **[CHANGELOG.md](CHANGELOG.md)** for the full, versioned release history (this project
+follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and
+[Semantic Versioning](https://semver.org/)).
+
 ## 🤝 Contributing
 
 We'd love your help making settfex better! Here's how:

settfex-0.4.0/RELEASING.md

@@ -0,0 +1,73 @@
+# Releasing settfex
+
+settfex publishes to PyPI through **one canonical path: pushing a `vX.Y.Z` git tag.**
+
+The tag triggers [`.github/workflows/release.yml`](.github/workflows/release.yml), which:
+
+1. validates the tag matches `pyproject.toml`,
+2. runs the full CI gate (ruff, format, mypy, pytest),
+3. builds the sdist + wheel,
+4. publishes to PyPI via an **OIDC Trusted Publisher** (no API token), and
+5. creates the GitHub Release with the changelog body + built artifacts.
+
+There is intentionally **no second PyPI upload path in the repo** — the workflow is the only
+thing that runs `twine`. Its publish step uses `skip-existing: true`, so re-tagging (or a one-off
+manual rescue) never hard-fails on an already-published file.
+
+## Cut a release
+
+1. Bump the version in **both** `pyproject.toml` and `settfex/__init__.py` (keep them in sync).
+2. Add a `## [X.Y.Z] - YYYY-MM-DD` section to `CHANGELOG.md`.
+3. Commit, open a PR, and merge to `main`.
+4. From an up-to-date `main`, tag and push:
+
+   ```bash
+   git checkout main && git pull --ff-only
+   git tag -a vX.Y.Z -m "settfex X.Y.Z"
+   git push origin vX.Y.Z
+   ```
+
+   CI does the rest — watch:
+   <https://github.com/lumduan/settfex/actions/workflows/release.yml>
+
+> **Maintainer convenience.** A local, gitignored `scripts/publish.sh` performs the same tag
+> push behind pre-flight checks (version sync between `pyproject.toml` and `settfex/__init__.py`,
+> a clean/synced `main`, the CHANGELOG section, and tag uniqueness). It never runs `twine`; it
+> only tags. It is not shipped in the repo because the tag push above is the real interface.
+
+## One-time setup: PyPI Trusted Publisher (required for the OIDC publish)
+
+This must be done once on pypi.org or the publish step will fail. On
+<https://pypi.org/manage/project/settfex/settings/publishing/>, add a **GitHub Actions**
+publisher:
+
+| Field | Value |
+|---|---|
+| Owner | `lumduan` |
+| Repository | `settfex` |
+| Workflow name | `release.yml` |
+| Environment | `pypi` |
+
+Then create the `pypi` environment under **GitHub → Settings → Environments** (it can be empty;
+the workflow references `environment: pypi`).
+
+## Break-glass: manual publish (fallback only)
+
+Use **only** if the tag/CI path is unavailable (e.g. an Actions outage). Requires a
+project-scoped token in a gitignored `.env` (`PYPI_TOKEN=pypi-…`):
+
+```bash
+rm -rf dist
+uv run python -m build
+uv run twine check dist/*
+uv run twine upload dist/* --username __token__ --password "$PYPI_TOKEN"
+```
+
+Prefer the tag-driven path. Because CI uses `skip-existing: true`, a later tag for the same
+version still succeeds and just backfills the GitHub Release.
+
+## Recommended follow-up
+
+Single-source the version (e.g. Hatchling `[tool.hatch.version] path = "settfex/__init__.py"`
+with `dynamic = ["version"]`) so `pyproject.toml` and the package can never drift again. The
+release workflow's validate step reads `project.version`, so adjust it if you switch.

settfex-0.4.0/docs/settfex/services/set/earnings_call.md

@@ -0,0 +1,187 @@
+# SET Earnings Call (Opportunity Day) Service
+
+## Overview
+
+The Earnings Call Service fetches the SET **"Earnings Call (OPPDAY)"** calendar — the
+Opportunity Day presentations listed at
+<https://opportunity-day.setgroup.or.th/en/earnings-call>. It returns typed Pydantic models
+and an optional pandas DataFrame whose columns are exactly what an earnings-call dashboard
+needs: `stock_name`, `company_name`, `earnings_call_date`, `video_clip_time`, `youtube_url`.
+
+Unlike the main SET API, the opportunity-day backend (`https://api.lcp.setgroup.or.th/api/v1`)
+is **stateless** — no Incapsula bot wall, no cookies, no auth. The service therefore uses a
+plain sessionless fetcher (no cookie warm-up).
+
+## Quick Start
+
+```python
+import asyncio
+from settfex.services.set import get_earnings_calls, get_earnings_calls_dataframe
+
+async def main():
+    # Typed models
+    response = await get_earnings_calls()
+    for item in response.items:
+        print(item.symbol, item.company_name_clean, item.youtube_url)
+
+    # …or straight to a DataFrame (requires: pip install settfex[dataframe])
+    df = await get_earnings_calls_dataframe()
+    print(df)
+
+asyncio.run(main())
+```
+
+## The 5 DataFrame columns
+
+| Column | Source |
+|---|---|
+| `stock_name` | `symbol` (e.g. `HANN`) |
+| `company_name` | `company_name` with the leading `"<SYMBOL>: "` prefix stripped |
+| `earnings_call_date` | `meeting_date` (tz-aware UTC) as a `date` |
+| `video_clip_time` | `period` — the clip **duration** shown on the card, e.g. `"45:00"` |
+| `youtube_url` | derived from the thumbnail `image_path`, e.g. `https://www.youtube.com/watch?v=…` |
+
+`youtube_url` (and `youtube_video_id`) are `None` for upcoming items with no recording.
+
+> ⚠️ **The `period` field has two meanings.** In the **list** response (used for
+> `video_clip_time`) it is the clip **duration** (`"45:00"`, MM:SS). In the **detail**
+> response (enrichment) it is the meeting **clock-time range** (`"16:15 - 17:00"`), surfaced
+> separately as `EarningsCallDetail.meeting_time`. The list duration is authoritative and is
+> never overwritten by enrichment.
+
+## Models
+
+### `EarningsCallItem`
+
+- `id: int`, `name: str` (Thai presentation title), `symbol: str`, `industry: str`
+- `company_name: str` — raw, e.g. `"HANN: MUKDAHAN INTERNATIONAL HOSPITAL …"`
+- `meeting_date: datetime` — tz-aware UTC
+- `image_path: str | None`, `view_mode: bool | None`, `period: str | None`
+- **Derived** (computed): `company_name_clean: str`, `youtube_video_id: str | None`,
+  `youtube_url: str | None`
+- `detail: EarningsCallDetail | None` — populated only when `enrich=True`
+
+### `EarningsCallResponse`
+
+- `no_records: int` — total records across all pages
+- `items: list[EarningsCallItem]`, `count` property
+- `to_dataframe(columns=None) -> pandas.DataFrame` — defaults to the 5 columns above;
+  additional selectable columns: `company_name_raw`, `earnings_call_datetime`,
+  `youtube_video_id`, `id`, `name`, `industry`, `view_mode`. Unknown column → `ValueError`;
+  pandas missing → `ImportError`.
+
+### `EarningsCallDetail` (enrichment)
+
+`video_link`, `company_name_th`, `meeting_time` (the clock-time range), `document_link`,
+`snapshot_link`, `round_name`, `type`, `type_id`, `year`, `round`, `has_qa`, …
+
+### `FilterOption`
+
+`id: int | str`, `name: str` (ids are ints for types/years/trusts/stages, string codes for
+industries/markets/themes).
+
+## Service Class
+
+### `EarningsCallService(config: FetcherConfig | None = None)`
+
+`use_session` is always coerced to `False` for this stateless host; all other `FetcherConfig`
+settings (timeout, retries, impersonation, rate limit) are honored.
+
+#### `fetch_earnings_calls(...) -> EarningsCallResponse`
+
+```python
+response = await EarningsCallService().fetch_earnings_calls(
+    type_id=1,        # 1=Earnings Call/OPPDAY, 2=Digital Roadshow, 3=C-Sign
+    quarter_id=0,     # 0=all quarters; see fetch_filter_years()
+    keyword=None,     # free-text symbol/company search (normalized)
+    industries_id=None,
+    start=1,          # 1-based page number
+    page_size=12,
+    language="en",    # "en" or "th"
+    enrich=False,     # opt-in per-item detail (bounded concurrency)
+)
+```
+
+#### `fetch_all_earnings_calls(..., max_records=None, max_pages=None, throttle=0.3)`
+
+Auto-paginates, **bounded and polite** — reuses one fetcher, sleeps `throttle` seconds between
+pages, and stops at the first short page, once `no_records` is reached, or when a cap is hit.
+
+> The API honors `page_size` up to ~100 but **rejects very large values** (e.g. 500), which
+> surfaces as a clear `ResponseParseError`/`ValidationError`. The defaults (12 for a single
+> page, 50 for `fetch_all`) stay safely under the cap — prefer iterating pages over an
+> oversized `page_size`.
+
+```python
+service = EarningsCallService()
+response = await service.fetch_all_earnings_calls(max_records=200)  # at most 200, polite
+df = response.to_dataframe()
+```
+
+#### `fetch_earnings_calls_raw(...) -> dict`
+
+Raw JSON dict (no validation), for debugging.
+
+#### Filter helpers
+
+`fetch_filter_types()`, `fetch_filter_years()`, `fetch_filter_industries()`,
+`fetch_filter_markets()`, `fetch_filter_themes()`, `fetch_filter_trusts()`,
+`fetch_filter_stages()` → `list[FilterOption]`.
+
+## Convenience Functions
+
+- `get_earnings_calls(...) -> EarningsCallResponse`
+- `get_earnings_calls_dataframe(..., columns=None) -> pandas.DataFrame`
+
+Both fetch a **single page** by default (mirroring `get_stock_list`). For the full calendar,
+use `fetch_all_earnings_calls()` then `to_dataframe()`.
+
+## Usage Examples
+
+### Filter by quarter and type
+
+```python
+service = EarningsCallService()
+years = await service.fetch_filter_years()          # find the quarter id you want
+q1_2026 = next(y for y in years if y.name == "Quater 1/2026").id
+response = await service.fetch_earnings_calls(type_id=1, quarter_id=q1_2026, page_size=50)
+```
+
+### Search a single company
+
+```python
+response = await get_earnings_calls(keyword="HANN")
+for item in response.items:
+    print(item.meeting_date.date(), item.youtube_url)
+```
+
+### Enrich with detail (video link, Thai name, meeting time)
+
+```python
+response = await get_earnings_calls(page_size=10, enrich=True)
+for item in response.items:
+    if item.detail:
+        print(item.symbol, item.detail.meeting_time, item.detail.video_link)
+```
+
+## Optional dependency: pandas
+
+`to_dataframe()` / `get_earnings_calls_dataframe()` need pandas, which is an **optional**
+extra (the rest of the service works without it):
+
+```bash
+pip install "settfex[dataframe]"   # or: uv add pandas
+```
+
+## API Endpoints
+
+```
+POST https://api.lcp.setgroup.or.th/api/v1/investor/search/archive      # list (primary)
+GET  https://api.lcp.setgroup.or.th/api/v1/investor/vdo/{id}            # detail (enrich)
+GET  https://api.lcp.setgroup.or.th/api/v1/investor/filter/{name}       # filter options
+```
+
+## Related Services
+
+- [Stock List Service](list.md) — discover all SET/mai stocks
+- [AsyncDataFetcher](../../utils/data_fetcher.md) — low-level HTTP client (now supports POST)

{settfex-0.2.1 → settfex-0.4.0}/examples/README.md

@@ -21,8 +21,9 @@ Complete tutorial series covering all 11 SET services:
 9. **Trading Statistics** - Historical performance (multi-period)
 10. **Price Performance** - Stock vs sector vs market comparison
 11. **Financial Statements** - Balance sheet, income, cash flow
+12. **Earnings Call (Opportunity Day)** - OPPDAY calendar with YouTube links → DataFrame → CSV
 
-**Total**: 11 notebooks + comprehensive guide
+**Total**: 12 notebooks + comprehensive guide
 
 ## Quick Start