settfex 0.22.2__tar.gz → 0.24.0__tar.gz

{settfex-0.22.2 → settfex-0.24.0}/.github/workflows/dependency-drift.yml

@@ -21,6 +21,17 @@ permissions:
   contents: read
   issues: write
 
+# Serialise runs. This does NOT stop a double *refresh* -- the two runs on 2026-09-19 were separate
+# manual dispatches 20 minutes apart, each lasting ~16 s, so they never overlapped and a group would
+# have changed nothing. What it does guard is the read-modify-write below: two OVERLAPPING runs
+# could both find no open issue, both pass the `-z "$NUMBER"` check, and CREATE TWO standing issues
+# -- which then permanently breaks the "exactly one" invariant this workflow depends on.
+# `cancel-in-progress: false` on purpose: cancelling mid-write could leave the issue body replaced
+# and its comment missing.
+concurrency:
+  group: dependency-drift
+  cancel-in-progress: false
+
 jobs:
   report:
     name: Outdated report
@@ -157,5 +168,17 @@ jobs:
               --body-file body.md
           else
             gh issue edit "$NUMBER" --body-file body.md
-            gh issue comment "$NUMBER" --body "Refreshed $(date -u +%F) by the dependency-drift workflow."
+            # Comment at most ONCE per day. The body edit above is idempotent -- it is replaced
+            # wholesale and carries its own date header -- but the comment is append-only, so a
+            # second dispatch on the same day left #109 with two identical "Refreshed" comments
+            # (observed 2026-09-19, 20 minutes apart). The comment exists to raise a notification,
+            # and a second notification for an unchanged report is noise.
+            TODAY=$(date -u +%F)
+            ALREADY=$(gh issue view "$NUMBER" --json comments \
+              --jq "[.comments[] | select(.body | contains(\"Refreshed ${TODAY}\"))] | length")
+            if [ "${ALREADY:-0}" -eq 0 ]; then
+              gh issue comment "$NUMBER" --body "Refreshed ${TODAY} by the dependency-drift workflow."
+            else
+              echo "Already refreshed today (${ALREADY} comment(s)); body updated, comment skipped."
+            fi
           fi

{settfex-0.22.2 → settfex-0.24.0}/.github/workflows/release.yml

@@ -12,6 +12,11 @@ on:
     tags:
       - 'v[0-9]+.[0-9]+.[0-9]+'
       - 'v[0-9]+.[0-9]+.[0-9]+-*'
+      # PEP 440 spells a pre-release with NO hyphen (0.24.0rc1); SemVer uses one (0.24.0-rc1).
+      # The tag mirrors the pyproject version, which must be PEP 440, so both spellings are
+      # accepted. Without this line `v0.24.0rc1` matched neither pattern and the workflow simply
+      # never ran -- a tag push that looks successful and publishes nothing.
+      - 'v[0-9]+.[0-9]+.[0-9]+[a-z]+[0-9]+'
 
 permissions:
   contents: write   # create GitHub Release + upload assets
@@ -36,7 +41,10 @@ jobs:
           VERSION="${TAG#v}"
           echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
 
-          if [[ "$TAG" =~ -(alpha|beta|rc) ]]; then
+          # The hyphen is OPTIONAL: PEP 440 writes `0.24.0rc1`, so requiring `-rc` would have
+          # classified the first PEP 440 pre-release this repo ever tagged as a FULL release and
+          # marked it "Latest" on GitHub -- the opposite of the intent.
+          if [[ "$TAG" =~ -?(alpha|beta|rc)[0-9]*$ ]]; then
             echo "is_prerelease=true" >> "$GITHUB_OUTPUT"
           else
             echo "is_prerelease=false" >> "$GITHUB_OUTPUT"
@@ -177,9 +185,26 @@ jobs:
           import re, sys
           version = sys.argv[1]
           content = open("CHANGELOG.md").read()
-          pattern = rf"(?m)^## \[{re.escape(version)}\][^\n]*\n(.*?)(?=^## \[|\Z)"
-          match = re.search(pattern, content, re.DOTALL)
-          notes = match.group(1).strip() if match else f"Release v{version}"
+
+          def section(heading: str) -> str | None:
+              pattern = rf"(?m)^## \[{re.escape(heading)}\][^\n]*\n(.*?)(?=^## \[|\Z)"
+              found = re.search(pattern, content, re.DOTALL)
+              return found.group(1).strip() if found else None
+
+          # A pre-release documents the version it is a candidate FOR: `0.24.0rc1` is described by
+          # the `## [0.24.0]` section, and duplicating that section under an rc heading would mean
+          # maintaining two copies of the same notes. So fall back to the base version.
+          # Without this the body silently became the stub "Release v0.24.0rc1" -- a release that
+          # looks fine and carries none of its own notes.
+          base = re.match(r"^(\d+\.\d+\.\d+)", version)
+          notes = section(version)
+          if notes is None and base is not None and base.group(1) != version:
+              notes = section(base.group(1))
+              if notes is not None:
+                  notes = f"> Pre-release of **{base.group(1)}**.\n\n{notes}"
+          if notes is None:
+              print(f"::error::No CHANGELOG section for {version} or its base version")
+              sys.exit(1)
           with open("release_notes.txt", "w") as f:
               f.write(notes + "\n")
           PYEOF

{settfex-0.22.2 → settfex-0.24.0}/AGENTS.md

@@ -107,12 +107,37 @@ Indices: `get_index_list(lang)`, `get_index_info(symbol, lang)`,
 
 | I want… | Call |
 |---|---|
-| resolve a company to its SEC id | `resolve_company(query, lang)` |
+| resolve a company to its SEC id | `resolve_company(query, lang, allow_name_match=False)` |
 | list filings (financial statements, 56-1, 56-2, ratios, MD&A) | `get_sec_documents(query, types=..., from_date=..., to_date=...)` |
 | download the actual file(s) | `download_sec_document(target)` / `download_sec_documents(targets)` |
 
 Dates here are **dd/mm/yyyy**. Pass a wide window to see full year history.
 
+⚠️ **Not every SET symbol is an SEC issuer.** ETFs, warrants, DWs and `-F` foreign lines do not
+file, so resolving one of them raises rather than guessing (0.24.0):
+
+| outcome | exception | what to do |
+|---|---|---|
+| nothing matched | `CompanyNotFoundError` | report that no issuer exists; do not retry |
+| several matched, none flagged | `AmbiguousCompanyError` | read `exc.candidates` (each a `CompanyMatch`) and ask which one, or pass an exact symbol |
+| **exactly one matched, not flagged** | `AmbiguousCompanyError` | the site did not recognise your query as an *identifier*, so that row is a substring hit on a company **name**. If you meant a name, pass `allow_name_match=True`; if you meant a symbol, it is not an SEC issuer |
+
+**Searching by company name?** Pass `allow_name_match=True` — a name never flags, so a name lookup
+always lands in that third row:
+
+```python
+await get_sec_documents("CP ALL PUBLIC COMPANY LIMITED", allow_name_match=True)
+await resolve_company("ปตท", allow_name_match=True)   # still raises: 17 candidates, none flagged
+```
+
+It only ever affects the **single**-candidate case. Several unflagged candidates stay ambiguous
+whatever you intended.
+
+Both are **`ValueError`s, not `FetchError`s**, because the request succeeded — retrying returns the
+same answer forever, so `except FetchError: retry` must not be what catches them. Before 0.24.0 the
+second case returned an arbitrary alphabetically-first company: `CHINA` (an ETF) resolved to
+`ASEAN CHINA INVESTMENT FUND L.P.` and every filing listed under it was the wrong company's.
+
 `lang="th"` works and returns the **Thai-language filing documents** — different files from the
 English ones, not a translated index. Years and dates come back as **C.E.** in the model even
 though the Thai page states them in the Buddhist era (`2568` → `2025`). Free-text cells
@@ -130,16 +155,35 @@ listing where **every** usable row was lost raises `IncompleteListingError` rath
 transport: a failed request raises `FetchError`, and a body that is not a listing page raises
 `ParseError`, instead of parsing to zero rows and looking like "this issuer filed nothing".
 
-One thing deliberately does **not** raise: a broken "display all results" page. That section keeps
-its truncated inline rows and the shortfall shows in `completeness()` — so check that before
-treating a section as complete. As of 2026-09-20 SEC's Thai `fs-kf` page answers HTTP 500, which is
-an upstream bug, not a settfex one.
+Two things deliberately do **not** raise. A broken "display all results" page: that section keeps
+its truncated inline rows and the shortfall shows in `completeness()`. And **one failing report
+code**: the others keep their documents, and the failure is recorded on
+`docs.accounting.failed_codes` (with a WARNING). So after a call that returned normally, check
+`docs.accounting.has_losses` before treating the result as complete — an exception is no longer how
+a partial failure announces itself. `repr(docs)` states it too.
+
+As of 2026-09-20 SEC's Thai `fs-kf` page answers HTTP 500, which is an upstream bug, not a settfex
+one; it shows up as a `key_financial_ratio` shortfall on Thai listings.
+
+As of 0.24.0 `SecDocumentList` is a **Pydantic model** `{documents, accounting, reported_counts}`
+that still iterates, indexes and slices like the list it used to be — and a **slice keeps the
+accounting** (of the whole call, not of the slice). So `model_dump()` and JSON carry the
+completeness signal, which matters here more than anywhere: what you receive from a tool call is
+JSON, so a signal that does not serialize does not reach you at all.
+
+⚠️ `isinstance(docs, list)` is now `False` — it fails *silently*, by taking the other branch. Use
+`docs.documents` where a real list is needed. `sorted(docs)` and `list(docs)` still give plain
+lists, so sort `docs.documents`.
+
+⚠️ A section whose "display all results" page failed lands on `accounting.degraded_sections` and
+sets `has_losses` — that is how the live Thai `fs-kf` HTTP 500 above surfaces.
 
 `download_sec_documents(...)` returns a `DownloadResult` — a list of the files that downloaded,
 which also carries `.failed` (each with its target and reason) and `.is_complete`. Check it before
 reporting a batch as done; dead links on the SEC host arrive as HTML under HTTP 200, not as errors.
-⚠️ Read `.failed` off **that** object: it is a `list` subclass, so slicing, `sorted()`, `list()` and
-comprehensions all return a plain `list` and drop the failure report without warning.
+Also a Pydantic model since 0.24.0 (`{files, failed, requested}` + computed `is_complete`), so the
+failure report survives `model_dump()` and slicing. ⚠️ `isinstance(files, list)` is `False`; use
+`files.files`.
 
 ### ThaiBMA bonds — `from settfex.services.thaibma import ...`
 
@@ -225,23 +269,62 @@ being wrong, so none of them will announce itself.
 
 ## Errors you should expect
 
+Everything is importable from one place:
+
 ```python
 from settfex.exceptions import (
-    FetchError,            # HTTP/transport failure; carries .status_code and .symbol
-    SymbolNotFoundError,   # subclass of FetchError; HTTP 404, may carry .suggestion
-    StaleDataError,        # ThaiBMA rolled back and you asked it to raise
-    InvalidSymbolError,    # empty symbol — raised before any request
-    InvalidLanguageError,  # unrecognized lang
-    InvalidDateError,      # malformed date string — raised before any request
+    # --- the FETCH family: `except FetchError` catches all of these ---
+    FetchError,              # HTTP/transport failure; carries .status_code and .symbol
+    HTTPStatusError,         # a non-2xx, with .url and .report_code as data
+    SymbolNotFoundError,     # HTTP 404 on a SET endpoint; may carry .suggestion
+    StaleDataError,          # ThaiBMA rolled back and you asked it to raise
+    ParseError,              # a response arrived intact and could not be mapped
+    IncompleteListingError,  # a ParseError: rows classified, then every one was lost
+    # --- INPUT errors: ValueErrors, NOT caught by `except FetchError` ---
+    CompanyNotFoundError,    # SEC: the search ran and matched no issuer
+    AmbiguousCompanyError,   # SEC: several matched, none flagged; carries .candidates
+    InvalidSymbolError,      # empty symbol — raised before any request
+    InvalidLanguageError,    # unrecognized lang
+    InvalidDateError,        # malformed date string — raised before any request
 )
-from settfex.utils.parsing import ResponseParseError
+from settfex.utils.parsing import ResponseParseError   # also a ParseError since 0.24.0
 ```
 
-`InvalidSymbolError`, `InvalidLanguageError` and `InvalidDateError` are raised **before** any
-network call, so they always mean your arguments are wrong, never that the API is down.
+**The split is the thing to internalise: a `FetchError` may be worth retrying; a `ValueError`
+never is.** An input error means the request *succeeded* and your argument was wrong, so a retry
+loop on one spins forever. `InvalidSymbolError`, `InvalidLanguageError` and `InvalidDateError` are
+raised before any network call at all.
+
+⚠️ Two "not found" taxonomies coexist today: a SET 404 is a `SymbolNotFoundError` (a `FetchError`),
+while the SEC equivalent is a `CompanyNotFoundError` (a `ValueError`). Catch both if you handle
+both hosts. Unifying them is tracked on #135.
+
+⚠️ `ResponseParseError` is also what a **WAF block page** currently surfaces as — right family,
+wrong diagnosis. If you see it repeatedly from one host, **stop and back off**; do not retry.
 
 ---
 
+## Timed instructions
+
+If you are told to do something at a particular time, that instruction needs **a date, a clock time
+and a timezone** — `2026-09-21 17:00 ICT`. Relative words (*today*, *tonight*, *after close*) are
+ambiguous the moment a conversation spans midnight or is resumed later, and they give no signal
+that they have gone stale.
+
+**Check the current time before acting on one.** If the window has passed, say so and ask rather
+than substituting the nearest equivalent — the reason a window was chosen (avoiding market hours,
+avoiding another system's traffic) usually does not survive being moved by a day.
+
+## Communication language
+
+- All prose you write is in English: reports and chat replies to the operator, commit messages,
+  PR descriptions, GitHub issues and comments, docs, ADRs, and code comments.
+- Thai appears only as verbatim source data: document titles, labels (e.g. `สอบทาน`), company
+  names, URLs, quoted page text, and fixture contents. Keep it exactly as the source has it —
+  never translate or transliterate the data itself.
+- When a Thai value's meaning matters to the reader, add an English gloss next to it:
+  `สอบทาน` (reviewed).
+
 ## Working on the repo itself
 
 ```bash
@@ -271,3 +354,10 @@ settfex is **not officially affiliated** with SET or TFEX. It reads **public** m
 Browser impersonation and session caching exist to access that public data reliably and to
 *reduce* request volume (~25× fewer requests) — not to evade rate limits or terms of service.
 Respect both.
+
+**If you are sweeping many symbols, budget it.** These are other people's servers, and they push
+back: a 929-symbol sweep at concurrency 8 drew connection resets and then a WAF block page — an
+**HTTP 200 whose body reads `Request Rejected`** — for every request for about an hour
+(2026-09-20). Use concurrency 1 with jittered pauses, decide a request budget before you start,
+prefer a stratified sample over a census, and **stop at the first block signal** rather than
+retrying into it.