From 5e589d01771e5e8b1194c7b8bf46661ac29e7b1e Mon Sep 17 00:00:00 2001 From: ShengranYan Date: Sun, 1 Nov 2026 09:11:18 +0800 Subject: [PATCH 1/3] feat: add bounded HTML income fallback for quarterly 6-Ks Reuse EX-99 earnings tables when recent 6-Ks have no XBRL. Keep quarterly amounts separate from change columns and retain reporting currency, scale, source and caveats. Verify TSM 0001046179-26-000726: net income TWD 763,064 million and reported EPS NT$29.43. Preserve the 10-Q and XBRL paths. Fixes #1824 --- changelog.d/1824.added.md | 1 + docs/guides/financial-data.md | 46 ++++ edgar/_html_financials.py | 236 ++++++++++++++++++ edgar/entity/core.py | 41 ++- tests/fixtures/html/issue1824/README.md | 17 ++ .../issue1824/a3q26e_withguidancexfinal.htm | 12 + .../html/issue1824/tsm-20261015x6k.htm | 12 + .../issue1824/tsm-monthend6kx20261022.htm | 12 + .../test_07lk101_no_xbrl_hollow_financials.py | 8 +- tests/issues/regression/test_issue_1824.py | 220 ++++++++++++++++ 10 files changed, 591 insertions(+), 14 deletions(-) create mode 100644 changelog.d/1824.added.md create mode 100644 edgar/_html_financials.py create mode 100644 tests/fixtures/html/issue1824/README.md create mode 100644 tests/fixtures/html/issue1824/a3q26e_withguidancexfinal.htm create mode 100644 tests/fixtures/html/issue1824/tsm-20261015x6k.htm create mode 100644 tests/fixtures/html/issue1824/tsm-monthend6kx20261022.htm create mode 100644 tests/issues/regression/test_issue_1824.py diff --git a/changelog.d/1824.added.md b/changelog.d/1824.added.md new file mode 100644 index 000000000..066228265 --- /dev/null +++ b/changelog.d/1824.added.md @@ -0,0 +1 @@ +**`get_quarterly_financials()` can read untagged 6-K income tables.** A bounded search skips monthly notices and reuses EX-99 earnings tables with explicit quarterly periods, currency, scale and footnotes. TSM's `0001046179-26-000726` now supplies TWD 763,064 million net income. HTML results have `xb=None`; other statements remain unavailable. (GH #1824) diff --git a/docs/guides/financial-data.md b/docs/guides/financial-data.md index 099bf6f0e..dfc1cc63f 100644 --- a/docs/guides/financial-data.md +++ b/docs/guides/financial-data.md @@ -118,6 +118,52 @@ income = quarterly.income_statement() | Annual (10-K) | `company.get_financials()` | | Quarterly (10-Q) | `company.get_quarterly_financials()` | +### Foreign issuers and untagged 6-K earnings + +When no 10-Q exists, the method examines up to 10 recent unamended 6-Ks, +newest first. Each filing's XBRL takes precedence. If XBRL is absent, an +EX-99 HTML earnings exhibit can provide a **table-backed income statement**. +A monthly notice without an income statement is skipped. Increase the explicit +bound with `company.get_quarterly_financials(max_6k_filings=20)` if necessary; +this does not fetch older submission-history files. + +```python +from edgar import Company + +quarterly = Company("TSM").get_quarterly_financials() +if quarterly is not None: + income = quarterly.income_statement() + print(income.to_dataframe()) + print(quarterly.get_net_income()) + if quarterly.xb is None: + print(income.currency, income.scale) + print(income.source_url) + print(income.notes) +``` + +For TSM's October 15, 2026 release (`0001046179-26-000726`), the reported net +income is TWD 763,064 million. `get_net_income()` and `to_dataframe()` return +**763,064,000,000 TWD**, while `income.dataframe` retains the reported millions. +EPS remains unscaled: the release's `EPS (NT$)` row is **29.43**, not millions +of dollars. The row is reported EPS; this adapter does not infer a basic/diluted +classification or an ADR conversion. + +HTML results have `xb=None`. The income statement is a `FinancialTable`, not +an XBRL `Statement`: it supports `.dataframe`, `.to_dataframe()` and the +earnings-table display methods, but not XBRL rendering, facts or dimensional +views. `get_revenue()`, `get_gross_profit()`, `get_operating_income()` and +`get_net_income()` support recognized income rows. Other statements and +unavailable metrics return `None`; they are not reconstructed. `period_offset` +walks the actual quarterly **comparison columns** in date order, which need +not be consecutive quarters. + +Currency and scale must be explicit near the table; annual/YTD, unknown-period, +change-percent and ambiguous duplicate-period columns are not treated as +quarterly amounts. Source URLs and nearby footnotes travel with the table, +including TSM's note that the current figures had not been approved by its +Board of Directors. Unsupported formats still return `None`; this limited +fallback does not promise coverage of every foreign issuer's HTML or PDF. + --- diff --git a/edgar/_html_financials.py b/edgar/_html_financials.py new file mode 100644 index 000000000..22466b709 --- /dev/null +++ b/edgar/_html_financials.py @@ -0,0 +1,236 @@ +"""Conservative, income-statement-only fallback for untagged 6-K exhibits. + +Reuse the earnings parser; do not fabricate an XBRL object or infer missing +statements, currencies, or quarterly periods from the filing date. +""" +import json +import re +from dataclasses import dataclass, field +from typing import Optional + +import pandas as pd + +from edgar.earnings import ( + EarningsRelease, + FinancialTable, + RowType, + Scale, + _is_change_column, + _parse_period_header, + find_earnings_exhibits, +) +from edgar.exceptions import ValidationError +from edgar.financials import Financials + +_REVENUE = ('total revenue', 'total revenues', 'net sales', 'net revenue', 'revenue', 'revenues') +_NET_INCOME = ('net income attributable to owners of the parent', + 'net income attributable to shareholders of the parent', + 'net income', 'net income (loss)', 'net loss', 'net earnings') +_CURRENCIES = { + 'TWD': r'NT\$|\bTWD\b|New Taiwan [Dd]ollars', + 'USD': r'US\$|\bUSD\b|U\.?S\.? [Dd]ollars', + 'EUR': r'€|\bEUR\b|\beuros?\b', + 'CNY': r'\bRMB\b|\bCNY\b|[Rr]enminbi', + 'HKD': r'HK\$|\bHKD\b|Hong Kong [Dd]ollars', + 'JPY': r'\bJPY\b|Japanese [Yy]en', +} + + +def _currency(text): + matches = [code for code, pattern in _CURRENCIES.items() if re.search(pattern, text, re.I)] + return matches[0] if len(matches) == 1 else None + + +def _quarter(header, filing_year): + if _is_change_column(header) or re.search(r'\b(?:YTD|TTM|FY|annual|year.to.date)\b', header, re.I): + return None + info = _parse_period_header(header) + if info['duration_months'] == 3: + return info['period_end'].toordinal() + if info['duration_months'] is not None: + return None + # Compact fiscal-quarter labels need not imply calendar-quarter dates. + match = re.search(r'\b(?:([1-4])Q\s*(\d{4}|\d{2})|Q([1-4])\s*(\d{4}|\d{2}))\b', header, re.I) + if match: + quarter, year = int(match[1] or match[3]), match[2] or match[4] + year = int(year) if len(year) == 4 else filing_year // 100 * 100 + int(year) + if year > filing_year + 1: + year -= 100 + # Same ordering domain as ordinal dates; only used to sort columns. + from datetime import date + return date(year, quarter * 3, 1).toordinal() + return None + + +def _table_context(release, table): + """Read nearby unit declarations and footnotes, not narrative USD amounts.""" + node = release.document.tables[table.raw_index] + parent = node.parent + while parent is not None and len(parent.children) == 1 and parent.parent is not None: + node, parent = parent, parent.parent + if parent is None: + return [], [] + position = next(i for i, sibling in enumerate(parent.children) if sibling is node) + + def text(sibling): + return (sibling.content or sibling.text() or '').strip() + + before = [text(s) for s in parent.children[max(0, position - 3):position]] + after = [text(s) for s in parent.children[position + 1:position + 5]] + return [table.title or '', *before], [s for s in after if s] + + +@dataclass +class _HTMLIncomeStatement(FinancialTable): + currency: str = '' + source_url: str = '' + notes: tuple = field(default_factory=tuple) + + def to_dataframe(self, **kwargs): + """Actual currency amounts; EPS/ratios stay unscaled. Source labels remain.""" + frame = self.scaled_dataframe.reset_index(names='label') + frame.attrs.update(source='HTML', currency=self.currency, reported_scale=self.scale.value, + source_url=self.source_url, notes=self.notes) + return frame + + def to_context(self, detail='standard'): + # FinancialTable's general formatter describes dollar amounts as USD. + # This table has an explicit reporting currency and may instead be TWD. + return (f'HTML income statement | {self.currency} {self.scale}\n' + f'Source: {self.source_url}\n' + self.dataframe.to_string() + + '\n' + '\n'.join(self.notes)) + + def to_json(self, include_metadata=True): + result = json.loads(super().to_json(include_metadata=include_metadata)) + if include_metadata: + result['metadata'].update(source='HTML', currency=self.currency, + source_url=self.source_url, notes=self.notes) + return json.dumps(result, indent=2, default=str) + + def to_facts_dataframe(self): + raise NotImplementedError('HTML financials do not synthesize XBRL facts; use to_dataframe()') + + def __rich__(self): + from rich.console import Group + from rich.text import Text + return Group(Text(f'HTML income statement | {self.currency} {self.scale} | {self.source_url}'), + super().__rich__(), *(Text(note) for note in self.notes)) + + +class _HTMLFinancials(Financials): + def __init__(self, filing, statement): + super().__init__(None) + self.source_filing = filing + self.source_url = statement.source_url + self.currency = statement.currency + self.notes = statement.notes + self._income = statement + + def income_statement(self, *, view=None): + """A FinancialTable with to_dataframe(); no XBRL dimensional views.""" + if view is not None: + raise ValidationError('HTML income statements do not support XBRL views', + parameter='view', invalid_value=view) + return self._income + + def _value(self, labels, period_offset): + if not isinstance(period_offset, int) or period_offset < 0: + raise ValidationError('period_offset must be a non-negative integer', + parameter='period_offset', invalid_value=period_offset) + if period_offset >= len(self._income.periods): + return None + frame = self._income.dataframe + for label in labels: + positions = [i for i, name in enumerate(frame.index) if str(name).strip().lower() == label] + if len(positions) == 1: + value = frame.iloc[positions[0], period_offset] + if isinstance(value, (int, float)) and pd.notna(value): + return value * self._income.scale.value + return None + + def get_revenue(self, period_offset=0): + return self._value(_REVENUE, period_offset) + + def get_net_income(self, period_offset=0): + return self._value(_NET_INCOME, period_offset) + + def get_operating_income(self, period_offset=0): + return self._value(('income from operations', 'operating income', 'operating loss'), period_offset) + + def get_gross_profit(self, period_offset=0): + return self._value(('gross profit', 'gross profit (loss)'), period_offset) + + def get_currency_symbol(self): + return {'TWD': 'NT$', 'USD': '$', 'EUR': '€', 'CNY': '¥', 'HKD': 'HK$', 'JPY': '¥'}[self.currency] + + def to_context(self): + return (f'Financials: HTML income statement ({self.currency}); xb=None\n' + f'Source: {self.source_url}\n' + 'Only the reported income statement is available; other statements return None.\n' + + '\n'.join(self.notes)) + + def __str__(self): + return f'Financials(HTML income statement, {self.currency}, {self.source_filing.accession_no})' + + def __rich__(self): + return self._income.__rich__() + + +def _extract_6k_income_statement(filing) -> Optional[Financials]: + """Return only an explicitly quarterly, currency-qualified income table. + + Absence is None; downloads and parser failures are not hidden. EX-99 exhibits + are discovered from filing attachments, never guessed from document names. + """ + if filing.form != '6-K': + return None + filing_year = int(str(filing.filing_date)[:4]) + for attachment in find_earnings_exhibits(filing.attachments): + release = EarningsRelease(attachment) + if release.document is None: + continue + table = release.income_statement + if table is None: + continue + columns = [(key, i) for i, col in enumerate(table.dataframe.columns) + if (key := _quarter(str(col), filing_year)) is not None] + if not columns or len({key for key, _ in columns}) != len(columns): + continue + labels = {str(label).strip().lower() for label in table.dataframe.index} + if not labels.intersection(_REVENUE) or not labels.intersection(_NET_INCOME): + continue + # A grouped/NCI table needs explicit parent attribution; do not return + # consolidated income as the owners' income via a loose label match. + if any('noncontrolling' in label or 'non-controlling' in label for label in labels): + if not labels.intersection(_NET_INCOME[:2]): + continue + context, notes = _table_context(release, table) + declarations = [m[0] for text in reversed(context) + if (m := re.search(r'(?:\(?\s*units?\s*:\s*|\(\s*(?:amounts?\s+)?in\s+)[^)\n]+', text, re.I))] + if not declarations or (currency := _currency(declarations[0])) is None: + continue + scale = Scale.detect(declarations[0]) + positions = [i for _, i in sorted(columns, reverse=True)] + frame = table.dataframe.iloc[:, positions].copy() + row_types = list(table.row_types) + for row, label in enumerate(frame.index): + if re.search(r'\beps\b|per share|per adr|per ads', str(label), re.I): + row_types[row] = RowType.PER_SHARE + # The existing parser preserves literal letter footnotes (29.43b). + # Retain the footnote text below, remove only a numeric suffix. + for col in range(len(frame.columns)): + raw = str(frame.iloc[row, col]) + match = re.fullmatch(r'(-?\d+(?:\.\d+)?)[a-z]', raw, re.I) + if match: + frame.iloc[row, col] = float(match[1]) + source_url = attachment.url + statement = _HTMLIncomeStatement( + dataframe=frame, scale=scale, title=table.title, + statement_type=table.statement_type, periods=list(frame.columns), + raw_index=table.raw_index, row_types=row_types, currency=currency, + source_url=source_url, notes=tuple([declarations[0], *notes]), + ) + result = _HTMLFinancials(filing, statement) + if result.get_revenue() is not None and result.get_net_income() is not None: + return result + return None diff --git a/edgar/entity/core.py b/edgar/entity/core.py index 9cd075501..b40d29111 100644 --- a/edgar/entity/core.py +++ b/edgar/entity/core.py @@ -31,7 +31,7 @@ from edgar.display.styles import get_style, SYMBOLS from edgar.entity.data import Address, CompanyData, EntityData from edgar.entity.entity_facts import EntityFacts, get_company_facts -from edgar.exceptions import CompanyFactsNotFoundError, CompanyNotFoundError +from edgar.exceptions import CompanyFactsNotFoundError, CompanyNotFoundError, ValidationError from edgar.entity.tickers import get_icon_from_ticker from edgar.financials import Financials from edgar.display.formatting import cik_text, datefmt, reverse_name @@ -628,19 +628,28 @@ def get_financials(self) -> Optional[Financials]: return Financials.extract(filing) return None - def get_quarterly_financials(self) -> Optional[Financials]: + def get_quarterly_financials(self, *, max_6k_filings: int = 10) -> Optional[Financials]: """ Get financial statements from this company's latest quarterly report. - Checks 10-Q first, then falls back to 6-K (foreign private issuers). - Returns a Financials object with the same interface as get_financials(), - but with quarterly data instead of annual. + Checks 10-Q first, then at most ``max_6k_filings`` recent unamended + 6-Ks (foreign private issuers). For each 6-K, XBRL takes precedence. + An untagged HTML earnings exhibit can supply a table-backed income + statement with explicit quarterly columns and currency units. + + The HTML result is a Financials with ``xb=None``. Its income_statement() + is a FinancialTable with to_dataframe(), currency, source_url and notes; + its income getters return actual currency amounts. Balance sheet and + cash flow are unavailable. XBRL-only operations are not supported. + + Args: + max_6k_filings: Positive bound on recent 6-Ks examined (default 10). + Does not load older submissions beyond the current filings list. Returns: Financials object, or None when there are no statements to read: - this company has filed no 10-Q or 6-K, or the latest one carries no - XBRL (most 6-Ks don't). It is never how a failure is reported; a - transport or parsing failure raises. + no 10-Q exists and no supported 6-K is found within the search bound. + Transport failures raise; unsupported HTML formats remain unavailable. Example:: @@ -648,13 +657,23 @@ def get_quarterly_financials(self) -> Optional[Financials]: quarterly.income_statement() quarterly.balance_sheet() """ + if isinstance(max_6k_filings, bool) or not isinstance(max_6k_filings, int) or max_6k_filings < 1: + raise ValidationError('max_6k_filings must be a positive integer', + parameter='max_6k_filings', invalid_value=max_6k_filings) tenq_filing = self.latest_tenq if tenq_filing is not None: return tenq_filing.financials # Fall back to 6-K (foreign private issuers) - filing = self.get_filings(form='6-K', amendments=False, trigger_full_load=False).latest() - if filing is not None: - return Financials.extract(filing) + from edgar._html_financials import _extract_6k_income_statement + + filings = self.get_filings(form='6-K', amendments=False, trigger_full_load=False) + for filing in filings.head(max_6k_filings): + financials = Financials.extract(filing) + if financials is not None: + return financials + financials = _extract_6k_income_statement(filing) + if financials is not None: + return financials return None @property diff --git a/tests/fixtures/html/issue1824/README.md b/tests/fixtures/html/issue1824/README.md new file mode 100644 index 000000000..db88f100e --- /dev/null +++ b/tests/fixtures/html/issue1824/README.md @@ -0,0 +1,17 @@ +# SEC source fixtures for issue 1824 + +Downloaded directly from SEC on 2026-11-01 before implementing the fallback. +The HTML files are saved response bytes, not edited table reconstructions or +VCR cassettes. Tests discover the earnings exhibit link in the primary 6-K. + +| File | Source | SHA-256 | +|---|---|---| +| a3q26e_withguidancexfinal.htm | https://www.sec.gov/Archives/edgar/data/1046179/000104617926000726/a3q26e_withguidancexfinal.htm | `43d51cc7eba069f9d27e8a4647304d37bdeae90127d5c38e1736d857c240f00d` | +| tsm-20261015x6k.htm | https://www.sec.gov/Archives/edgar/data/1046179/000104617926000726/tsm-20261015x6k.htm | `43a0be1d03e92a19e49e8e55b18a0165811a5a7a105a5a89f731b53022bc664f` | +| tsm-monthend6kx20261022.htm | https://www.sec.gov/Archives/edgar/data/1046179/000104617926000728/tsm-monthend6kx20261022.htm | `9183c7d03daf67fd0efa4547cdc7e37fbcaaf33a593e71f37d27dba7dbc24878` | + +Ground truth in the earnings exhibit: `(Unit: NT$ million, except for EPS)`; +net sales 1,494,243; gross profit 992,379; income from operations 876,445; +net income 763,064; reported EPS 29.43 (footnote b). Net income comparisons +are 452,302 for 3Q25 and 706,562 for 2Q26, with YoY/QoQ percentages interleaved. +Footnote a says the 3Q2026 figures have not been approved by the Board of Directors. diff --git a/tests/fixtures/html/issue1824/a3q26e_withguidancexfinal.htm b/tests/fixtures/html/issue1824/a3q26e_withguidancexfinal.htm new file mode 100644 index 000000000..891fed035 --- /dev/null +++ b/tests/fixtures/html/issue1824/a3q26e_withguidancexfinal.htm @@ -0,0 +1,12 @@ + +EX-99.1 +2 +a3q26e_withguidancexfinal.htm +EX-99.1 + + + + +Document
image_1.jpg
TSMC Reports Third Quarter EPS of NT$29.43


HSINCHU, Taiwan, R.O.C., Oct. 15, 2026 -- TSMC (TWSE: 2330, NYSE: TSM) today announced consolidated revenue of NT$1,494.24 billion, net income of NT$763.06 billion, and diluted earnings per share of NT$29.43 (US$4.60 per ADR unit) for the third quarter ended September 30, 2026.

Year-over-year, third quarter revenue increased 50.9%, while net income and diluted EPS both increased 68.7%. Compared to second quarter 2026, third quarter results represented a 17.6% increase in revenue and an 8.0% increase in net income. All figures were prepared in accordance with TIFRS on a consolidated basis.

In US dollars, third quarter revenue was $46.72 billion, which increased 41.2% year-over-year and increased 16.2% from the previous quarter.

Gross margin for the quarter was 66.4%, operating margin was 58.7%, and net profit margin was 51.1%.

In the third quarter, shipments of 2-nanometer accounted for 8% of total wafer revenue; 3-nanometer accounted for 33%; 5-nanometer accounted for 28%; and 7-nanometer accounted for 10%. Advanced technologies, defined as 7-nanometer and more advanced technologies, accounted for 79% of total wafer revenue.

“Our business in the third quarter was supported by strong demand for our leading-edge process technologies,” said Wendell Huang, Senior VP and Chief Financial Officer of TSMC. “Moving into fourth quarter 2026, we expect our business to be supported by continued strong demand for our leading-edge process technologies, including the steep ramp-up of our 2-nanometer technology.”

Based on the Company’s current business outlook, management expects the overall performance for fourth quarter 2026 to be as follows:


•Revenue is expected to be between US$52.3 billion and US$54.3 billion;

And, based on the exchange rate assumption of 1 US dollar to 31.8 NT dollars,

•Gross profit margin is expected to be between 65% and 67%;

•Operating profit margin is expected to be between 56.5% and 58.5%.


image_1.jpg
TSMC’s 2026 third quarter consolidated results:
(Unit: NT$ million, except for EPS)
3Q26
Amounta
3Q25
Amount
YoY
Inc. (Dec.) %
2Q26
Amount
QoQ
Inc. (Dec.) %
Net sales
1,494,243989,91850.91,270,38117.6
Gross profit
992,379588,54368.6860,31115.4
Income from operations
876,445500,68575.0766,60314.3
Income before tax
911,039525,36973.4862,4305.6
Net income
763,064452,30268.7706,5628.0
EPS (NT$)
29.43b
17.44c
68.7
27.25b
8.0
a: 3Q2026 figures have not been approved by Board of Directors
b: Based on 25,932 million weighted average outstanding shares
c: Based on 25,930 million weighted average outstanding shares




About TSMC
TSMC pioneered the pure-play foundry business model when it was founded in 1987, and has been the world’s leading dedicated semiconductor foundry ever since. The Company supports a thriving ecosystem of global customers and partners with the industry’s leading process technologies and portfolio of design enablement solutions to unleash innovation for the global semiconductor industry. With global operations spanning Asia, Europe, and North America, TSMC serves as a committed corporate citizen around the world.

TSMC deployed 305 distinct process technologies, and manufactured 12,682 products for 534 customers in 2025 by providing the broadest range of advanced, specialty and advanced packaging technology services. The Company is headquartered in Hsinchu, Taiwan. For more information please visit https://www.tsmc.com.

# # #

TSMC Spokesperson:
Wendell Huang
Senior Vice President and CFO
Media Contacts:
Nina Kao
Head of Public Relations
Tel: 886-3-563-6688 ext.712-5036
Mobile: 886-988-239-163
E-Mail: press@tsmc.com


Ulric Kelly
Public Relations
Tel: 886-3-563-6688 ext.712-6541
Mobile: 886-978-111-503
E-Mail: press@tsmc.com


+
+
diff --git a/tests/fixtures/html/issue1824/tsm-20261015x6k.htm b/tests/fixtures/html/issue1824/tsm-20261015x6k.htm new file mode 100644 index 000000000..4a5d8991d --- /dev/null +++ b/tests/fixtures/html/issue1824/tsm-20261015x6k.htm @@ -0,0 +1,12 @@ + +6-K +1 +tsm-20261015x6k.htm +6-K + + + + +Document

1934 Act Registration No. 1-14700
UNITED STATES
SECURITIES AND EXCHANGE COMMISSION
Washington, D.C. 20549
_____________________________
FORM 6-K
_____________________________
REPORT OF FOREIGN PRIVATE ISSUER
PURSUANT TO RULE 13a-16 OR 15d-16 UNDER
THE SECURITIES EXCHANGE ACT OF 1934
For the month of October 2026
(Commission File Number: 001-14700)
_____________________________
Taiwan Semiconductor Manufacturing Company Limited
(Translation of Registrant’s Name Into English)
_____________________________
No. 8, Li-Hsin Road 6
Hsinchu Science Park
Hsinchu 300-096, Taiwan
Republic of China
(Address of Principal Executive Offices)
_____________________________
Indicate by check mark whether the registrant files or will file annual reports under cover of Form 20-F or Form 40-F.
Form 20-F  x            Form 40-F  o
Indicate by check mark if the registrant is submitting the Form 6-K in papers as permitted by Regulation S-T Rule 101(b)(1):o
Indicate by check mark if the registrant is submitting the Form 6-K in papers as permitted by Regulation S-T Rule 101(b)(7):o



SIGNATURES
Pursuant to the requirements of the Securities Exchange Act of 1934, the registrant has duly caused this report to be signed on its behalf by the undersigned, thereunto duly authorized.


Taiwan Semiconductor Manufacturing Company Limited
Date: October 15, 2026By   /s/ Wendell Huang
  Wendell Huang
   Senior Vice President & Chief Financial Officer




Exhibits

+
+
diff --git a/tests/fixtures/html/issue1824/tsm-monthend6kx20261022.htm b/tests/fixtures/html/issue1824/tsm-monthend6kx20261022.htm new file mode 100644 index 000000000..6aa34936c --- /dev/null +++ b/tests/fixtures/html/issue1824/tsm-monthend6kx20261022.htm @@ -0,0 +1,12 @@ + +6-K +1 +tsm-monthend6kx20261022.htm +6-K + + + + +Document

1934 Act Registration No. 1-14700
UNITED STATES
SECURITIES AND EXCHANGE COMMISSION
Washington, D.C. 20549
_____________________________
FORM 6-K
_____________________________
REPORT OF FOREIGN PRIVATE ISSUER
PURSUANT TO RULE 13a-16 OR 15d-16 UNDER
THE SECURITIES EXCHANGE ACT OF 1934
For the month of October 2026
(Commission File Number: 001-14700)
_____________________________
Taiwan Semiconductor Manufacturing Company Limited
(Translation of Registrant’s Name Into English)
_____________________________
No. 8, Li-Hsin Road 6
Hsinchu Science Park
Hsinchu 300-096, Taiwan
Republic of China
(Address of Principal Executive Offices)
_____________________________
Indicate by check mark whether the registrant files or will file annual reports under cover of Form 20-F or Form 40-F.
Form 20-F  x            Form 40-F  o
Indicate by check mark if the registrant is submitting the Form 6-K in papers as permitted by Regulation S-T Rule 101(b)(1):o
Indicate by check mark if the registrant is submitting the Form 6-K in papers as permitted by Regulation S-T Rule 101(b)(7):o



SIGNATURES
Pursuant to the requirements of the Securities Exchange Act of 1934, the registrant has duly caused this report to be signed on its behalf by the undersigned, thereunto duly authorized.


Taiwan Semiconductor Manufacturing Company Limited
Date: October 22, 2026By/s/ Wendell Huang
Wendell Huang
Senior Vice President and Chief Financial Officer
   




Taiwan Semiconductor Manufacturing Company Limited
("TSMC"; NYSE: TSM)
This is to report 1) the changes in the shareholdings of TSMC board of directors, executive officers and shareholders who own more than 10% of total outstanding common shares of TSMC; 2) the changes in the pledge of TSMC common shares by TSMC board of directors, executive officers and shareholders who own more than 10% of total outstanding common shares of TSMC; 3) the acquisition and disposition of assets by TSMC and its subsidiaries; 4) the capital appropriations approved by TSMC board of directors; 5) the unsecured bonds issued by TSMC and its subsidiaries and 6) the cancellation of TSMC common shares for the month of September 2026.
1.The changes in the shareholdings of TSMC board of directors, executive officers and shareholders who own more than 10% of total outstanding common shares of TSMC:
TitleNameNumber of shares held as ofChanges
8/31/20269/30/2026
Chairman & Chief Executive OfficerC.C. Wei8,152,6108,356,985204,375 
Executive Vice President and Co-Chief Operating OfficerY.P. Chyn9,362,0429,394,24632,204 
Executive Vice President and Co-Chief Operating OfficerY.J. Mii1,254,0571,286,26132,204 
Senior Vice President and Deputy Co-Chief Operating Officer / Chief Information Security OfficerCliff Hou723,205771,22948,024 
Senior Vice President and Deputy Co-Chief Operating OfficerKevin Zhang329,663349,97620,313 
Senior Vice President, General Counsel and Corporate Governance OfficerSylvia Fang1,310,2981,350,80140,503 
Senior Vice President and Chief Financial OfficerWendell Huang1,811,5431,831,85620,313 
Senior Vice PresidentY.L. Wang1,497,9211,510,80212,881 
Senior Vice PresidentT.S. Chang317,638346,58028,942 
Senior Vice PresidentMichael Wu829,171842,05212,881 
Senior Vice PresidentGeoffrey Yeap213,375243,38330,008 
Senior Vice PresidentJonathan Lee512,032524,91312,881 
Vice PresidentMin Cao542,349555,23012,881 
Vice PresidentSimon Jang445,879454,0548,175 
Vice PresidentC.S. Yoo2,869,4462,877,6218,175 
Vice PresidentJun He120,119140,73520,616 
Vice President and Chief Information OfficerChris Horng-Dar Lin143,184164,37221,188 



TitleNameNumber of shares held as ofChanges
8/31/20269/30/2026
Vice PresidentArthur Chuang3,488,3053,509,36821,063 
Vice PresidentL.C. Lu291,716299,8918,175 
Vice PresidentK.C. Hsu190,924199,0998,175 
Vice PresidentRay Chuang345,738365,23919,501 

Note: Shareholdings include shares held by the related parties.
2.The changes in the pledge of TSMC common shares by TSMC board of directors, executive officers and shareholders who own more than 10% of total outstanding common shares of TSMC:
None.
3.The acquisition and disposition of assets by TSMC and its subsidiaries:
None.
4.The capital appropriations approved by TSMC board of directors:
None.
5.The unsecured bonds issued by TSMC and its subsidiaries:
None.
6.The cancellation of TSMC common shares:
None.

+
+
diff --git a/tests/issues/regression/test_07lk101_no_xbrl_hollow_financials.py b/tests/issues/regression/test_07lk101_no_xbrl_hollow_financials.py index 416bc5664..06085d352 100644 --- a/tests/issues/regression/test_07lk101_no_xbrl_hollow_financials.py +++ b/tests/issues/regression/test_07lk101_no_xbrl_hollow_financials.py @@ -70,14 +70,16 @@ def test_six_k_financials_is_none_without_xbrl(no_xbrl): assert report.financials is None -def test_get_quarterly_financials_is_none_when_the_6k_has_no_xbrl(no_xbrl): +def test_get_quarterly_financials_is_none_when_the_6k_has_no_supported_statements(no_xbrl): from edgar.entity import core class _Filings: - def latest(self): + def head(self, n): filing = _Filing() filing.form = "6-K" - return filing + filing.filing_date = "2026-10-22" + filing.attachments = [] + return [filing][:n] class _ForeignFiler: latest_tenq = None diff --git a/tests/issues/regression/test_issue_1824.py b/tests/issues/regression/test_issue_1824.py new file mode 100644 index 000000000..b96fe6f53 --- /dev/null +++ b/tests/issues/regression/test_issue_1824.py @@ -0,0 +1,220 @@ +"""Bounded 6-K HTML income-statement fallback, with the reported TSM amounts. + +GitHub Issue: https://github.com/dgunning/edgartools/issues/1824 + +SEC originals downloaded unchanged on 2026-11-01, before the implementation: +TSM 6-K 0001046179-26-000726, a3q26e_withguidancexfinal.htm (2026-10-15): +net income TWD 763,064 million, net sales TWD 1,494,243 million, EPS NT$29.43. +Comparison amounts: 2Q26 net income 706,562 million, 3Q25 452,302 million. +The latest 6-K 0001046179-26-000728 is a monthly notice, not this release. +""" +import json +from datetime import date +from pathlib import Path +from types import SimpleNamespace + +import pytest +from bs4 import BeautifulSoup + +from edgar._html_financials import _extract_6k_income_statement +from edgar.earnings import RowType, Scale +from edgar.entity import Company +from edgar.financials import Financials +from edgar.xbrl import XBRL + +FIXTURES = Path(__file__).parents[2] / 'fixtures' / 'html' / 'issue1824' +EARNINGS = '0001046179-26-000726' +MONTHLY = '0001046179-26-000728' + + +class Attachment: + def __init__(self, name, content, accession=EARNINGS): + self.document = name + self.document_type = 'EX-99.1' + self.description = 'Press release' + self.content = content + self.url = f'https://www.sec.gov/Archives/edgar/data/1046179/{accession.replace("-", "")}/{name}' + + def is_html(self): + return True + + +class Filings(list): + def head(self, count): + return self[:count] + + +def filing(accession, attachments): + return SimpleNamespace(form='6-K', accession_no=accession, filing_date=date(2026, 10, 22), + attachments=attachments) + + +def company(filings): + class ForeignCompany: + latest_tenq = None + + def get_filings(self, **kwargs): + assert kwargs == dict(form='6-K', amendments=False, trigger_full_load=False) + return Filings(filings) + + return ForeignCompany() + + +@pytest.fixture +def release(): + # Discover the exhibit through the actual primary document's links. + primary = BeautifulSoup((FIXTURES / 'tsm-20261015x6k.htm').read_text(), 'lxml') + links = {a['href'] for a in primary.select('a[href]')} + exhibit = 'a3q26e_withguidancexfinal.htm' + assert exhibit in links + return filing(EARNINGS, [Attachment(exhibit, (FIXTURES / exhibit).read_text())]) + + +@pytest.fixture +def monthly(): + name = 'tsm-monthend6kx20261022.htm' + # Even treating the whole monthly notice as an exhibit must not accept it. + return filing(MONTHLY, [Attachment(name, (FIXTURES / name).read_text(), MONTHLY)]) + + +@pytest.fixture +def no_xbrl(monkeypatch): + monkeypatch.setattr(XBRL, 'from_filing', lambda f: None) + + +def test_tsm_reported_values_periods_units_and_caveat(release): + result = _extract_6k_income_statement(release) + assert isinstance(result, Financials) + assert result.xb is None + assert result.source_filing.accession_no == EARNINGS + assert result.currency == 'TWD' + assert result.get_currency_symbol() == 'NT$' + assert result.get_net_income() == 763_064_000_000 + assert result.get_net_income(1) == 706_562_000_000 + assert result.get_net_income(2) == 452_302_000_000 + assert result.get_net_income(3) is None + assert result.get_revenue() == 1_494_243_000_000 + assert result.get_gross_profit() == 992_379_000_000 + assert result.get_operating_income() == 876_445_000_000 + statement = result.income_statement() + assert statement.scale is Scale.MILLIONS + assert list(statement.dataframe.columns) == ['3Q26\nAmounta', '2Q26\nAmount', '3Q25\nAmount'] + assert statement.dataframe.loc['EPS (NT$)'].tolist() == [29.43, 27.25, 17.44] + assert statement.get_row_type('EPS (NT$)', 5) is RowType.PER_SHARE + frame = statement.to_dataframe().set_index('label') + assert frame.loc['EPS (NT$)'].tolist() == [29.43, 27.25, 17.44] + assert frame.loc['Net income'].tolist() == [763_064_000_000, 706_562_000_000, 452_302_000_000] + assert frame.attrs['currency'] == 'TWD' + exported = json.loads(statement.to_json()) + assert exported['metadata']['currency'] == 'TWD' + assert exported['metadata']['source'] == 'HTML' + assert any('Board of Directors' in note for note in exported['metadata']['notes']) + with pytest.raises(NotImplementedError, match='do not synthesize XBRL facts'): + statement.to_facts_dataframe() + assert any('not been approved by Board of Directors' in note for note in result.notes) + assert any('25,932 million' in note for note in result.notes) + assert 'HTML' in str(result) and 'HTML' in result.to_context() + assert 'actual USD' not in statement.to_context() + assert 'not been approved by Board of Directors' in statement.to_context() + assert result.source_url.endswith('a3q26e_withguidancexfinal.htm') + assert result.balance_sheet() is None + assert result.cash_flow_statement() is None + assert result.get_total_assets() is None + assert result.get_financial_metrics()['net_income'] == 763_064_000_000 + + +def test_monthly_notice_is_not_a_quarterly_income_statement(monthly): + assert _extract_6k_income_statement(monthly) is None + + +def test_company_passes_monthly_to_reach_real_earnings_release(release, monthly, no_xbrl): + result = Company.get_quarterly_financials(company([monthly, release])) + assert result.source_filing.accession_no == EARNINGS + assert result.get_net_income() == 763_064_000_000 + + +def test_search_is_bounded(release, monthly, no_xbrl): + assert Company.get_quarterly_financials(company([monthly, release]), max_6k_filings=1) is None + assert Company.get_quarterly_financials(company([])) is None + + +def test_xbrl_still_wins_and_does_not_download_html(release, monkeypatch): + expected = Financials(object()) + monkeypatch.setattr(Financials, 'extract', lambda f: expected) + release.attachments = None # Access would fail if the HTML fallback runs. + assert Company.get_quarterly_financials(company([release])) is expected + + +def test_tenq_still_wins(): + expected = object() + c = SimpleNamespace(latest_tenq=SimpleNamespace(financials=expected)) + assert Company.get_quarterly_financials(c) is expected + + +@pytest.mark.parametrize('bound', [0, -1, True, 1.5, '10']) +def test_invalid_search_bound_raises(bound): + with pytest.raises(ValueError, match='positive integer'): + Company.get_quarterly_financials(company([]), max_6k_filings=bound) + + +def test_transport_failure_is_not_swallowed(release, monkeypatch): + def fail(f): + raise ConnectionError('SEC unavailable') + + monkeypatch.setattr(XBRL, 'from_filing', fail) + with pytest.raises(ConnectionError, match='SEC unavailable'): + Company.get_quarterly_financials(company([release])) + + +def test_unknown_currency_remains_unsupported(release): + content = release.attachments[0].content + release.attachments[0].content = content.replace('NT$ million', 'million') + assert _extract_6k_income_statement(release) is None + + +def test_annual_or_ambiguous_periods_are_not_presented_as_quarterly(release): + content = release.attachments[0].content + # No quarter labels remains an annual/unknown-period table. + release.attachments[0].content = content.replace('3Q26', '2026').replace('3Q25', '2025').replace('2Q26', '2026') + assert _extract_6k_income_statement(release) is None + # Two amount columns for the same quarter could be separate segments or currencies. + release.attachments[0].content = content.replace('2Q26', '3Q26') + assert _extract_6k_income_statement(release) is None + + +def test_compact_ytd_headers_are_not_quarters(release): + content = release.attachments[0].content + for label in ['3Q26', '3Q25', '2Q26']: + content = content.replace(label, 'YTD ' + label) + release.attachments[0].content = content + assert _extract_6k_income_statement(release) is None + + +def test_narrative_currency_is_not_a_table_unit_declaration(release): + original = release.attachments[0].content + release.attachments[0].content = original.replace( + '(Unit: NT$ million, except for EPS)', 'Forecast profit in NT$ million') + assert release.attachments[0].content != original + assert _extract_6k_income_statement(release) is None + + +def test_exhibit_download_failure_is_not_swallowed(release): + class UnavailableAttachment(Attachment): + @property + def content(self): + raise ConnectionError('exhibit download failed') + + attachment = object.__new__(UnavailableAttachment) + attachment.document = 'ex99.htm' + attachment.document_type = 'EX-99.1' + attachment.description = 'earnings' + release.attachments = [attachment] + with pytest.raises(ConnectionError, match='exhibit download failed'): + _extract_6k_income_statement(release) + + +@pytest.mark.parametrize('offset', [-1, 1.5]) +def test_invalid_period_offset_raises(release, offset): + result = _extract_6k_income_statement(release) + with pytest.raises(ValueError, match='non-negative integer'): + result.get_net_income(offset) From d4b4c1ef5e7cb408c9ce579f2a87bf695c5d6258 Mon Sep 17 00:00:00 2001 From: ShengranYan Date: Sun, 1 Nov 2026 14:45:42 +0800 Subject: [PATCH 2/3] fix(financials): align HTML DataFrame fields and parameters --- changelog.d/1824.added.md | 2 +- docs/guides/financial-data.md | 35 +++- edgar/_html_financials.py | 121 +++++++++++++- edgar/entity/core.py | 6 +- tests/issues/regression/test_issue_1824.py | 185 ++++++++++++++++++++- 5 files changed, 332 insertions(+), 17 deletions(-) diff --git a/changelog.d/1824.added.md b/changelog.d/1824.added.md index 066228265..f986f0fcd 100644 --- a/changelog.d/1824.added.md +++ b/changelog.d/1824.added.md @@ -1 +1 @@ -**`get_quarterly_financials()` can read untagged 6-K income tables.** A bounded search skips monthly notices and reuses EX-99 earnings tables with explicit quarterly periods, currency, scale and footnotes. TSM's `0001046179-26-000726` now supplies TWD 763,064 million net income. HTML results have `xb=None`; other statements remain unavailable. (GH #1824) +**`get_quarterly_financials()` can read untagged 6-K income tables.** A bounded search skips monthly notices and reads EX-99 quarterly tables with currency, scale and footnotes. TSM's `0001046179-26-000726` supplies TWD 763,064 million net income. HTML DataFrames share Statement metadata columns and unit/standardization flags; source XBRL tags stay null and XBRL-only options raise. Results have `xb=None`; other statements remain unavailable. (GH #1824) diff --git a/docs/guides/financial-data.md b/docs/guides/financial-data.md index dfc1cc63f..3eccb7e6d 100644 --- a/docs/guides/financial-data.md +++ b/docs/guides/financial-data.md @@ -133,7 +133,7 @@ from edgar import Company quarterly = Company("TSM").get_quarterly_financials() if quarterly is not None: income = quarterly.income_statement() - print(income.to_dataframe()) + print(income.to_dataframe(include_unit=True, include_point_in_time=True)) print(quarterly.get_net_income()) if quarterly.xb is None: print(income.currency, income.scale) @@ -150,8 +150,37 @@ classification or an ADR conversion. HTML results have `xb=None`. The income statement is a `FinancialTable`, not an XBRL `Statement`: it supports `.dataframe`, `.to_dataframe()` and the -earnings-table display methods, but not XBRL rendering, facts or dimensional -views. `get_revenue()`, `get_gross_profit()`, `get_operating_income()` and +earnings-table display methods, but not XBRL rendering or facts. +The exported DataFrame has the same non-period columns as `Statement.to_dataframe()`: +`concept`, `label`, `standard_concept` and the structural/linkbase metadata. +`concept` and unavailable XBRL metadata are null, never fabricated tags or hierarchies. +Original row labels and reported period headers remain unchanged; compact fiscal +quarters are not converted to guessed calendar dates. The selected value columns +are also listed in `df.attrs['period_columns']`. + +`standard=True` (the default) maps exact, unambiguous HTML labels to existing +standard identifiers such as `Revenue`, `GrossProfit`, `OperatingIncomeLoss` +and `PretaxIncomeLoss`. Generic `Net income` and `EPS` remain unmapped: those +labels alone do not establish parent attribution or basic/diluted EPS. An +explicit parent-attributed income or basic/diluted EPS label can be mapped. +Unrecognized/adjusted labels remain unmapped, and `standard=False` leaves the +`standard_concept` column null without changing labels or values. As with +`Statement`, the legacy `include_standardization` flag does not override `standard`. +`df.attrs['standardization_source']` identifies the HTML label mapping; +the source URL, currency, original scale and notes are retained in `df.attrs`. + +`include_unit=True` adds per-row units (`twd` for amounts, `twdPerShare` for +TSM's EPS); values use actual currency amounts, not millions. Share-count units +are `shares`, reported percentages use `percent` without dividing by 100, and +unclassified rows have a null unit. `include_point_in_time=True` adds `False` +for these quarterly-duration values. To select a comparison column, pass its +exact reported header, for example `income.to_dataframe(period_filter=income.periods[-1])`. +An unknown column raises `ValueError`, and misspelled keyword arguments raise `TypeError`. +Explicit `view` and `period_view`, `presentation=False` (raw XBRL signs), and +`matrix=True` raise `NotImplementedError`; no requested XBRL operation is silently +ignored. This also applies to `quarterly.income_statement(view=...)`. + +`get_revenue()`, `get_gross_profit()`, `get_operating_income()` and `get_net_income()` support recognized income rows. Other statements and unavailable metrics return `None`; they are not reconstructed. `period_offset` walks the actual quarterly **comparison columns** in date order, which need diff --git a/edgar/_html_financials.py b/edgar/_html_financials.py index 22466b709..6dfed57a6 100644 --- a/edgar/_html_financials.py +++ b/edgar/_html_financials.py @@ -21,6 +21,7 @@ ) from edgar.exceptions import ValidationError from edgar.financials import Financials +from edgar.xbrl.presentation import ViewType, normalize_view _REVENUE = ('total revenue', 'total revenues', 'net sales', 'net revenue', 'revenue', 'revenues') _NET_INCOME = ('net income attributable to owners of the parent', @@ -34,6 +35,47 @@ 'HKD': r'HK\$|\bHKD\b|Hong Kong [Dd]ollars', 'JPY': r'\bJPY\b|Japanese [Yy]en', } +# These are existing standard concept identifiers, not invented source tags. +# Exact labels only: generic "Net income" does not establish parent attribution, +# and generic "EPS" does not establish basic versus diluted earnings per share. +_STANDARD_CONCEPTS = { + **dict.fromkeys(_REVENUE, 'Revenue'), + 'gross profit': 'GrossProfit', + 'gross profit (loss)': 'GrossProfit', + 'income from operations': 'OperatingIncomeLoss', + 'operating income': 'OperatingIncomeLoss', + 'operating loss': 'OperatingIncomeLoss', + 'income before tax': 'PretaxIncomeLoss', + 'income before taxes': 'PretaxIncomeLoss', + 'net income attributable to owners of the parent': 'NetIncome', + 'net income attributable to shareholders of the parent': 'NetIncome', + 'profit (loss)': 'ProfitLoss', +} +_XBRL_METADATA = ( + 'level', 'abstract', 'dimension', 'is_breakdown', 'dimension_axis', + 'dimension_member', 'dimension_member_label', 'dimension_label', 'balance', + 'weight', 'preferred_sign', 'parent_concept', 'parent_abstract_concept', +) + + +def _standard_concept(label, row_type): + label = ' '.join(str(label).lower().split()) + if row_type == RowType.PER_SHARE: + # Do not use an unqualified EPS row or prose elsewhere to guess a type. + match = re.fullmatch(r'(basic|diluted) (?:eps|(?:earnings|loss|earnings \(loss\)) per share)' + r'(?:\s*\((?:nt\$|us\$|hk\$|twd|usd|eur|cny|rmb|jpy|€|¥)\))?', label) + if match: + return {'basic': 'EarningsPerShareBasic', 'diluted': 'EarningsPerShareDiluted'}[match[1]] + return None + if row_type == RowType.AMOUNT: + return _STANDARD_CONCEPTS.get(label) + return None + + +def _unsupported_view(view): + if view is not None: + normalize_view(view) # Preserve the public API's invalid-view diagnostics. + raise NotImplementedError('view requires XBRL dimensions; HTML income tables have no dimensional views') def _currency(text): @@ -41,6 +83,16 @@ def _currency(text): return matches[0] if len(matches) == 1 else None +def _row_unit(label, row_type, reporting_currency): + if row_type not in (RowType.AMOUNT, RowType.PER_SHARE): + return {RowType.SHARES: 'shares', RowType.PERCENTAGE: 'percent'}.get(row_type) + currencies = [code for code, pattern in _CURRENCIES.items() if re.search(pattern, label, re.I)] + if len(currencies) > 1 or (not currencies and re.search(r'\((?:[A-Z]{3}|\$)\)', label)): + return None # Ambiguous or unsupported explicit row currency. + currency = (currencies[0] if currencies else reporting_currency).lower() + return f'{currency}PerShare' if row_type == RowType.PER_SHARE else currency + + def _quarter(header, filing_year): if _is_change_column(header) or re.search(r'\b(?:YTD|TTM|FY|annual|year.to.date)\b', header, re.I): return None @@ -86,11 +138,66 @@ class _HTMLIncomeStatement(FinancialTable): source_url: str = '' notes: tuple = field(default_factory=tuple) - def to_dataframe(self, **kwargs): - """Actual currency amounts; EPS/ratios stay unscaled. Source labels remain.""" - frame = self.scaled_dataframe.reset_index(names='label') + def to_dataframe(self, + period_filter: Optional[str] = None, + period_view: Optional[str] = None, + standard: bool = True, + view: ViewType = None, + *, + include_unit: bool = False, + include_point_in_time: bool = False, + include_standardization: bool = False, + presentation: bool = True, + matrix: bool = False) -> pd.DataFrame: + """Statement-compatible columns with honest HTML provenance. + + Amounts use actual currency units and EPS stays unscaled. Source XBRL + concepts and linkbase metadata are null. ``standard`` adds conservative + exact-label mappings without changing labels; the deprecated + ``include_standardization`` flag does not override it, as in Statement. + ``period_filter`` selects an exact source column from ``periods``. + XBRL period/dimensional views, raw-instance signs and equity matrices + are unavailable and raise rather than being silently ignored. + """ + for name, value in (('standard', standard), ('include_unit', include_unit), + ('include_point_in_time', include_point_in_time), + ('include_standardization', include_standardization), + ('presentation', presentation), ('matrix', matrix)): + if not isinstance(value, bool): + raise ValidationError(f'{name} must be a boolean', parameter=name, invalid_value=value) + _unsupported_view(view) + if period_view is not None: + if not isinstance(period_view, str): + raise ValidationError('period_view must be a string', parameter='period_view', invalid_value=period_view) + raise NotImplementedError('period_view requires XBRL periods; use period_filter with a source column') + if not presentation: + raise NotImplementedError('presentation=False requires raw XBRL signs; HTML preserves reported signs') + if matrix: + raise NotImplementedError('matrix=True is unavailable for HTML income tables') + + columns = list(self.periods) + if period_filter is not None: + if not isinstance(period_filter, str) or period_filter not in columns: + raise ValidationError(f'period_filter must be one of the reported columns: {columns}', + parameter='period_filter', invalid_value=period_filter) + columns = [period_filter] + frame = self.scaled_dataframe.loc[:, columns].reset_index(names='label') + row_types = [self.get_row_type(str(label), pos) for pos, label in enumerate(frame['label'])] + frame.insert(0, 'concept', None) + frame.insert(2, 'standard_concept', [ + _standard_concept(label, row_type) if standard else None + for label, row_type in zip(frame['label'], row_types, strict=True) + ]) + if include_unit: + frame['unit'] = [_row_unit(str(label), row_type, self.currency) + for label, row_type in zip(frame['label'], row_types, strict=True)] + if include_point_in_time: + frame['point_in_time'] = False # Explicit quarterly durations, never instants. + for name in _XBRL_METADATA: + frame[name] = None frame.attrs.update(source='HTML', currency=self.currency, reported_scale=self.scale.value, - source_url=self.source_url, notes=self.notes) + source_url=self.source_url, notes=self.notes, period_columns=columns, + standardization_source='HTML exact labels' if standard else None) return frame def to_context(self, detail='standard'): @@ -128,13 +235,11 @@ def __init__(self, filing, statement): def income_statement(self, *, view=None): """A FinancialTable with to_dataframe(); no XBRL dimensional views.""" - if view is not None: - raise ValidationError('HTML income statements do not support XBRL views', - parameter='view', invalid_value=view) + _unsupported_view(view) return self._income def _value(self, labels, period_offset): - if not isinstance(period_offset, int) or period_offset < 0: + if isinstance(period_offset, bool) or not isinstance(period_offset, int) or period_offset < 0: raise ValidationError('period_offset must be a non-negative integer', parameter='period_offset', invalid_value=period_offset) if period_offset >= len(self._income.periods): diff --git a/edgar/entity/core.py b/edgar/entity/core.py index b40d29111..2dc05f36b 100644 --- a/edgar/entity/core.py +++ b/edgar/entity/core.py @@ -639,8 +639,10 @@ def get_quarterly_financials(self, *, max_6k_filings: int = 10) -> Optional[Fina The HTML result is a Financials with ``xb=None``. Its income_statement() is a FinancialTable with to_dataframe(), currency, source_url and notes; - its income getters return actual currency amounts. Balance sheet and - cash flow are unavailable. XBRL-only operations are not supported. + its DataFrame has Statement metadata columns (unavailable XBRL metadata + is null), optional per-row units and conservative standard_concept + mappings. Income getters return actual currency amounts. Balance sheet + and cash flow are unavailable; requested XBRL-only operations raise. Args: max_6k_filings: Positive bound on recent 6-Ks examined (default 10). diff --git a/tests/issues/regression/test_issue_1824.py b/tests/issues/regression/test_issue_1824.py index b96fe6f53..2f2cf373c 100644 --- a/tests/issues/regression/test_issue_1824.py +++ b/tests/issues/regression/test_issue_1824.py @@ -8,11 +8,13 @@ Comparison amounts: 2Q26 net income 706,562 million, 3Q25 452,302 million. The latest 6-K 0001046179-26-000728 is a monthly notice, not this release. """ +import inspect import json from datetime import date from pathlib import Path from types import SimpleNamespace +import pandas as pd import pytest from bs4 import BeautifulSoup @@ -21,6 +23,8 @@ from edgar.entity import Company from edgar.financials import Financials from edgar.xbrl import XBRL +from edgar.xbrl.presentation import StatementView +from edgar.xbrl.statements import Statement FIXTURES = Path(__file__).parents[2] / 'fixtures' / 'html' / 'issue1824' EARNINGS = '0001046179-26-000726' @@ -102,8 +106,8 @@ def test_tsm_reported_values_periods_units_and_caveat(release): assert statement.dataframe.loc['EPS (NT$)'].tolist() == [29.43, 27.25, 17.44] assert statement.get_row_type('EPS (NT$)', 5) is RowType.PER_SHARE frame = statement.to_dataframe().set_index('label') - assert frame.loc['EPS (NT$)'].tolist() == [29.43, 27.25, 17.44] - assert frame.loc['Net income'].tolist() == [763_064_000_000, 706_562_000_000, 452_302_000_000] + assert frame.loc['EPS (NT$)', statement.periods].tolist() == [29.43, 27.25, 17.44] + assert frame.loc['Net income', statement.periods].tolist() == [763_064_000_000, 706_562_000_000, 452_302_000_000] assert frame.attrs['currency'] == 'TWD' exported = json.loads(statement.to_json()) assert exported['metadata']['currency'] == 'TWD' @@ -213,8 +217,183 @@ def content(self): _extract_6k_income_statement(release) -@pytest.mark.parametrize('offset', [-1, 1.5]) +@pytest.mark.parametrize('offset', [-1, 1.5, True, '1', None]) def test_invalid_period_offset_raises(release, offset): result = _extract_6k_income_statement(release) with pytest.raises(ValueError, match='non-negative integer'): result.get_net_income(offset) + + +@pytest.fixture(scope='module') +def nvda_statement(): + # Existing, unmodified SEC XBRL fixture: 0001045810-26-000021. This pins + # the public Statement schema, not a claim of matching TSM's fiscal dates. + return XBRL.from_directory(Path('tests/fixtures/xbrl/nvda/10k_2026')).statements.income_statement() + + +def test_html_and_xbrl_share_dataframe_parameters(release): + statement = _extract_6k_income_statement(release).income_statement() + html_params = inspect.signature(type(statement).to_dataframe).parameters + xbrl_params = inspect.signature(Statement.to_dataframe).parameters + assert list(html_params) == list(xbrl_params) + assert [(p.kind, p.default) for p in html_params.values()] == [ + (p.kind, p.default) for p in xbrl_params.values() + ] + + +@pytest.mark.parametrize('options', [ + {}, {'include_unit': True}, {'include_point_in_time': True}, + {'include_unit': True, 'include_point_in_time': True}, + {'standard': False}, {'include_standardization': True}, + {'standard': False, 'include_standardization': True}, +]) +def test_real_tsm_and_nvda_share_columns_and_standard_flag(release, nvda_statement, options): + statement = _extract_6k_income_statement(release).income_statement() + html = statement.to_dataframe(**options) + xbrl = nvda_statement.to_dataframe(**options) + html_periods = set(statement.periods) + xbrl_periods = {col for col in xbrl if col.startswith(('2026-', '2025-', '2024-'))} + assert [col for col in html if col not in html_periods] == [col for col in xbrl if col not in xbrl_periods] + # Source identity remains XBRL only; HTML label mappings are not source tags. + assert html['concept'].isna().all() + assert 'us-gaap_Revenues' in xbrl['concept'].to_numpy() + if options.get('standard', True): + assert set(html['standard_concept'].dropna()) <= set(xbrl['standard_concept'].dropna()) + for frame, label in [(html, 'Net sales'), (xbrl, 'Revenue')]: + revenue = frame.loc[frame['label'] == label].iloc[0] + if options.get('standard', True): + assert revenue['standard_concept'] == 'Revenue' + else: + assert pd.isna(revenue['standard_concept']) + + +def test_html_units_provenance_and_missing_xbrl_metadata(release): + statement = _extract_6k_income_statement(release).income_statement() + frame = statement.to_dataframe(include_unit=True, include_point_in_time=True).set_index('label') + assert frame['unit'].tolist() == ['twd'] * 5 + ['twdPerShare'] + assert frame['point_in_time'].tolist() == [False] * 6 + assert frame['standard_concept'].iloc[:4].tolist() == [ + 'Revenue', 'GrossProfit', 'OperatingIncomeLoss', 'PretaxIncomeLoss', + ] + assert frame['standard_concept'].iloc[4:].isna().all() + # Generic net income does not establish attribution, nor EPS basic/diluted. + assert frame.loc['Net income', '3Q26\nAmounta'] == 763_064_000_000 + assert frame.loc['EPS (NT$)', '3Q26\nAmounta'] == 29.43 + for column in ('concept', 'level', 'abstract', 'dimension', 'is_breakdown', + 'dimension_axis', 'dimension_member', 'dimension_member_label', + 'dimension_label', 'balance', 'weight', 'preferred_sign', + 'parent_concept', 'parent_abstract_concept'): + assert frame[column].isna().all(), column + assert frame.attrs['source'] == 'HTML' + assert frame.attrs['standardization_source'] == 'HTML exact labels' + assert frame.attrs['period_columns'] == statement.periods + assert frame.attrs['reported_scale'] == 1_000_000 + assert frame.attrs['source_url'].endswith('a3q26e_withguidancexfinal.htm') + assert any('Board of Directors' in note for note in frame.attrs['notes']) + + +def test_period_filter_selects_reported_comparative_column_without_mutation(release): + statement = _extract_6k_income_statement(release).income_statement() + original = statement.dataframe.copy(deep=True) + periods = list(statement.periods) + frame = statement.to_dataframe(period_filter='3Q25\nAmount', include_unit=True).set_index('label') + assert frame.attrs['period_columns'] == ['3Q25\nAmount'] + assert not set(periods[:2]).intersection(frame.columns) + assert frame.loc['Net income', '3Q25\nAmount'] == 452_302_000_000 + assert frame.loc['EPS (NT$)', '3Q25\nAmount'] == 17.44 + frame.loc['Net income', '3Q25\nAmount'] = 0 + pd.testing.assert_frame_equal(statement.dataframe, original) + assert statement.periods == periods + assert statement.to_dataframe().attrs['period_columns'] == periods + + +@pytest.mark.parametrize('value', ['', 'Q3 2025', 'duration_2025-07-01_2025-09-30', 1, True]) +def test_invalid_html_period_filter_is_not_silently_ignored(release, value): + statement = _extract_6k_income_statement(release).income_statement() + with pytest.raises(ValueError, match='period_filter.*reported columns'): + statement.to_dataframe(period_filter=value) + + +@pytest.mark.parametrize('options, message', [ + ({'period_view': 'Quarterly Comparison'}, 'period_view'), + ({'view': 'summary'}, 'view.*XBRL dimensions'), + ({'view': StatementView.STANDARD}, 'view.*XBRL dimensions'), + ({'presentation': False}, 'presentation=False'), + ({'matrix': True}, 'matrix=True'), +]) +def test_unavailable_xbrl_operations_raise_explicitly(release, options, message): + statement = _extract_6k_income_statement(release).income_statement() + with pytest.raises(NotImplementedError, match=message): + statement.to_dataframe(**options) + + +def test_html_income_accessor_and_converter_agree_about_views(release): + result = _extract_6k_income_statement(release) + with pytest.raises(NotImplementedError, match='view.*XBRL dimensions'): + result.income_statement(view='summary') + for call in (result.income_statement, result.income_statement().to_dataframe): + with pytest.raises(ValueError, match='Invalid view'): + call(view='misspelled') + + +@pytest.mark.parametrize('name', [ + 'standard', 'include_unit', 'include_point_in_time', + 'include_standardization', 'presentation', 'matrix', +]) +def test_html_boolean_parameters_reject_non_booleans(release, name): + statement = _extract_6k_income_statement(release).income_statement() + with pytest.raises(ValueError, match=f'{name} must be a boolean'): + statement.to_dataframe(**{name: 1}) + + +def test_html_period_view_type_and_unknown_keywords_raise(release): + statement = _extract_6k_income_statement(release).income_statement() + with pytest.raises(ValueError, match='period_view must be a string'): + statement.to_dataframe(period_view=1) + with pytest.raises(TypeError, match='unexpected keyword argument.*include_unt'): + statement.to_dataframe(include_unt=True) + + +def test_explicit_concept_labels_map_but_ambiguous_and_adjusted_labels_do_not(release): + # In-memory mutations test the inference boundary; SEC fixture bytes stay intact. + statement = _extract_6k_income_statement(release).income_statement() + statement.dataframe.index = [ + 'Adjusted revenue', 'Revenue growth', 'Net income attributable to owners of the parent', + 'Unrecognized income', 'Profit (loss)', 'Diluted EPS (NT$)', + ] + frame = statement.to_dataframe() + assert frame['standard_concept'].iloc[[0, 1, 3]].isna().all() + assert frame['standard_concept'].iloc[[2, 4, 5]].tolist() == ['NetIncome', 'ProfitLoss', 'EarningsPerShareDiluted'] + assert frame['concept'].isna().all() + statement.dataframe.index = [*statement.dataframe.index[:-1], 'Basic earnings per share (NT$)'] + assert statement.to_dataframe()['standard_concept'].iloc[-1] == 'EarningsPerShareBasic' + assert frame['label'].iloc[-1] == 'Diluted EPS (NT$)' + + +def test_row_types_and_explicit_row_currency_determine_units(release): + statement = _extract_6k_income_statement(release).income_statement() + statement.row_types = [RowType.AMOUNT, RowType.SHARES, RowType.PERCENTAGE, + RowType.OTHER, RowType.AMOUNT, RowType.PER_SHARE] + statement.dataframe.index = [*statement.dataframe.index[:-1], 'EPS (US$)'] + frame = statement.to_dataframe(include_unit=True) + assert frame['unit'].iloc[[0, 1, 2, 4, 5]].tolist() == ['twd', 'shares', 'percent', 'twd', 'usdPerShare'] + assert pd.isna(frame['unit'].iloc[3]) + assert frame['3Q26\nAmounta'].tolist() == [1_494_243_000_000, 992_379, 876_445, 911_039, 763_064_000_000, 29.43] + + +@pytest.mark.parametrize('label', ['Basic EPS (non-GAAP)', 'Diluted EPS (adjusted)', 'Adjusted diluted EPS (NT$)']) +def test_adjusted_eps_qualifiers_do_not_become_standard_gaap_eps(release, label): + statement = _extract_6k_income_statement(release).income_statement() + statement.dataframe.index = [*statement.dataframe.index[:-1], label] + frame = statement.to_dataframe() + assert pd.isna(frame['standard_concept'].iloc[-1]) + assert frame['3Q26\nAmounta'].iloc[-1] == 29.43 + + +@pytest.mark.parametrize('label', ['EPS (NT$ / US$)', 'EPS (GBP)', 'EPS ($)']) +def test_uncertain_row_currency_stays_null(release, label): + statement = _extract_6k_income_statement(release).income_statement() + statement.dataframe.index = [*statement.dataframe.index[:-1], label] + frame = statement.to_dataframe(include_unit=True) + assert pd.isna(frame['unit'].iloc[-1]) + assert frame['3Q26\nAmounta'].iloc[-1] == 29.43 From 2f1d23ace25a5c742262ebcb5c0da8414d8df276 Mon Sep 17 00:00:00 2001 From: ShengranYan Date: Sun, 1 Nov 2026 15:11:09 +0800 Subject: [PATCH 3/3] refactor(financials): simplify 6-K income extraction --- edgar/_html_financials.py | 77 +++++++++++++++++++++++++-------------- 1 file changed, 50 insertions(+), 27 deletions(-) diff --git a/edgar/_html_financials.py b/edgar/_html_financials.py index 6dfed57a6..c38ba2f2f 100644 --- a/edgar/_html_financials.py +++ b/edgar/_html_financials.py @@ -281,6 +281,49 @@ def __rich__(self): return self._income.__rich__() +def _quarter_column_positions(table, filing_year): + """Keep unique quarterly amount columns, newest comparison first.""" + columns = [(key, i) for i, col in enumerate(table.dataframe.columns) + if (key := _quarter(str(col), filing_year)) is not None] + if not columns or len({key for key, _ in columns}) != len(columns): + return [] + return [i for _, i in sorted(columns, reverse=True)] + + +def _has_income_totals(table): + labels = {str(label).strip().lower() for label in table.dataframe.index} + if not labels.intersection(_REVENUE) or not labels.intersection(_NET_INCOME): + return False + # A grouped/NCI table needs explicit parent attribution; do not return + # consolidated income as the owners' income via a loose label match. + has_nci = any('noncontrolling' in label or 'non-controlling' in label for label in labels) + return not has_nci or bool(labels.intersection(_NET_INCOME[:2])) + + +def _declared_table_units(context): + """Use the nearest explicit declaration, even if it is unsupported.""" + for text in reversed(context): + match = re.search(r'(?:\(?\s*units?\s*:\s*|\(\s*(?:amounts?\s+)?in\s+)[^)\n]+', text, re.I) + if match: + declaration = match[0] + currency = _currency(declaration) + return (declaration, currency, Scale.detect(declaration)) if currency else None + return None + + +def _clean_eps_rows(frame, row_types): + for row, label in enumerate(frame.index): + if not re.search(r'\beps\b|per share|per adr|per ads', str(label), re.I): + continue + row_types[row] = RowType.PER_SHARE + # The existing parser preserves literal letter footnotes (29.43b). + # Retain the footnote text below, remove only a numeric suffix. + for col in range(len(frame.columns)): + match = re.fullmatch(r'(-?\d+(?:\.\d+)?)[a-z]', str(frame.iloc[row, col]), re.I) + if match: + frame.iloc[row, col] = float(match[1]) + + def _extract_6k_income_statement(filing) -> Optional[Financials]: """Return only an explicitly quarterly, currency-qualified income table. @@ -297,43 +340,23 @@ def _extract_6k_income_statement(filing) -> Optional[Financials]: table = release.income_statement if table is None: continue - columns = [(key, i) for i, col in enumerate(table.dataframe.columns) - if (key := _quarter(str(col), filing_year)) is not None] - if not columns or len({key for key, _ in columns}) != len(columns): - continue - labels = {str(label).strip().lower() for label in table.dataframe.index} - if not labels.intersection(_REVENUE) or not labels.intersection(_NET_INCOME): + positions = _quarter_column_positions(table, filing_year) + if not positions or not _has_income_totals(table): continue - # A grouped/NCI table needs explicit parent attribution; do not return - # consolidated income as the owners' income via a loose label match. - if any('noncontrolling' in label or 'non-controlling' in label for label in labels): - if not labels.intersection(_NET_INCOME[:2]): - continue context, notes = _table_context(release, table) - declarations = [m[0] for text in reversed(context) - if (m := re.search(r'(?:\(?\s*units?\s*:\s*|\(\s*(?:amounts?\s+)?in\s+)[^)\n]+', text, re.I))] - if not declarations or (currency := _currency(declarations[0])) is None: + units = _declared_table_units(context) + if units is None: continue - scale = Scale.detect(declarations[0]) - positions = [i for _, i in sorted(columns, reverse=True)] + declaration, currency, scale = units frame = table.dataframe.iloc[:, positions].copy() row_types = list(table.row_types) - for row, label in enumerate(frame.index): - if re.search(r'\beps\b|per share|per adr|per ads', str(label), re.I): - row_types[row] = RowType.PER_SHARE - # The existing parser preserves literal letter footnotes (29.43b). - # Retain the footnote text below, remove only a numeric suffix. - for col in range(len(frame.columns)): - raw = str(frame.iloc[row, col]) - match = re.fullmatch(r'(-?\d+(?:\.\d+)?)[a-z]', raw, re.I) - if match: - frame.iloc[row, col] = float(match[1]) + _clean_eps_rows(frame, row_types) source_url = attachment.url statement = _HTMLIncomeStatement( dataframe=frame, scale=scale, title=table.title, statement_type=table.statement_type, periods=list(frame.columns), raw_index=table.raw_index, row_types=row_types, currency=currency, - source_url=source_url, notes=tuple([declarations[0], *notes]), + source_url=source_url, notes=tuple([declaration, *notes]), ) result = _HTMLFinancials(filing, statement) if result.get_revenue() is not None and result.get_net_income() is not None: