feat: Add XBRL dataclass models and methods for fetching company facts

- Introduced `Fact` and `Facts` models in `edgar/models.py` to represent XBRL data points and structured company facts.
- Implemented `get_facts()` method in `Company` class to return a `Facts` model.
- Updated `Xbrl` class with `get_facts()` method for fetching structured facts by CIK.
- Enhanced `company_concepts()` and `frames()` methods to accept an optional `taxonomy` parameter.
- Added sample usage script `samples/use_xbrl_facts.py` demonstrating the new functionality.
- Created unit tests for `Fact` and `Facts` models in `tests/test_xbrl_facts.py`.
- Updated `CHANGELOG.md` to document the new features and changes.

Author: areed1192

CHANGELOG.md

@@ -8,6 +8,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+
+- **edgar/models.py**: `Fact` and `Facts` XBRL dataclass models.
+  - `Facts` wraps the deeply nested `company_facts` JSON (4 levels) with `get(taxonomy, concept, unit=None)` returning a flat `list[Fact]` sorted by end date.
+  - `Facts.taxonomies` lists available namespaces (e.g. `['dei', 'us-gaap', 'ifrs-full']`).
+  - `Facts.concepts(taxonomy)` lists concept names within a taxonomy.
+  - `Facts.label()`, `Facts.description()`, `Facts.units()` for concept metadata.
+  - `Fact` wraps a single data point with `value`, `end`, `start`, `fiscal_year`, `fiscal_period`, `form`, `filed`, `frame` properties.
+- **xbrl.py**: `get_facts(cik)` method returning a structured `Facts` model.
+- **company.py**: `get_facts()` method returning a structured `Facts` model.
+- **tests/test_xbrl_facts.py**: 39 unit tests for `Fact`, `Facts`, `Company.get_facts()`, `Xbrl.get_facts()`, and taxonomy parameter support.
+
+### Changed
+
+- **xbrl.py**: `company_concepts()` and `frames()` now accept an optional `taxonomy` parameter (default `"us-gaap"`). Previously hardcoded to `us-gaap`, now supports `"ifrs-full"`, `"dei"`, or any other taxonomy.
 - **edgar/tickers.py**: New `Tickers` service for ticker/CIK/company name resolution via `sec.gov/files/company_tickers.json`.
   - `resolve_ticker("AAPL")` → zero-padded CIK string (`"0000320193"`).
   - `resolve_cik(320193)` → list of company entries (ticker, title, CIK).
@@ -38,19 +52,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **README.md**: Complete rewrite with hero example, full service table (15 services), usage examples for ticker resolution, fluent Company API, XBRL, filing search, downloads, response models, and badge row.
 - **samples/use_company.py**: Sample file demonstrating the fluent Company interface (creation by ticker/CIK, filings, submissions, XBRL, download).
 - **samples/use_models.py**: Sample file demonstrating structured dataclass response models (`Filing`, `CompanyInfo`, `Submission`).
+- **samples/use_xbrl_facts.py**: Sample file demonstrating `Facts` and `Fact` XBRL dataclass models (taxonomy browsing, concept retrieval, unit filtering, metadata, cross-taxonomy access).
 - **tests/test_rate_limiter.py**: 9 unit tests for the sliding-window rate limiter (under-limit, at-limit sleep, timestamp expiry, integration checks for all three request paths).
 
 ### Changed
+
 - **session.py**: Replaced counter-based rate limiter (`sleep 5s every 10 requests`) with a sliding-window algorithm using `collections.deque` of `time.monotonic()` timestamps. Sleeps only the minimum time needed when the 1-second window is full. `MAX_REQUESTS_PER_SECOND = 10` enforced per SEC policy.
 - **session.py**: Rate limiting now applies to all three outgoing request paths (`make_request()`, `fetch_page()`, `download()`). Previously `fetch_page()` and `download()` bypassed rate limiting entirely.
 
 ### Changed
+
 - Migrated from `setup.py` to `pyproject.toml` for modern packaging.
 - Relaxed dependency version pins to use minimum ranges instead of exact versions.
 - Updated minimum Python version to 3.9.
 - Excluded `samples/` and `tests/` from distributed package.
 
 ### Fixed
+
 - **enums.py**: Renamed `StateCodes` members from mixed-case (`Alabama`, `New_York`) to UPPER_CASE (`ALABAMA`, `NEW_YORK`) to follow Python enum naming conventions.
 - **utils.py**: Exception chaining — `except ValueError as exc` / `raise ... from exc` in `parse_dates`.
 - **session.py**: Replaced infinite retry loop with bounded retry (max 5) and exponential backoff.
@@ -90,11 +108,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **All examples**: Updated `EdgarClient()` → `EdgarClient(user_agent=...)` across 13 sample files, README.md, test file, and 55 docstring examples in 14 `edgar/` modules to reflect the required `user_agent` parameter.
 
 ### Removed
+
 - **`edgar/parser/xbrl.py`**: Deleted `XbrlFiling` stub class — never imported or referenced.
 - **`edgar/parser/`**: Removed empty directory that conflicted with `parser.py` module.
 - **`edgar/enums.py`**: Replaced monolithic 1581-line file with `edgar/enums/` package — one module per enum class (`state_codes.py`, `country_codes.py`, `filing_type_codes.py`, `sic_codes.py`, `other_filing_types.py`) plus `__init__.py` re-exporting all names. All existing `from edgar.enums import X` imports continue to work.
 
 ### Added
+
 - `py.typed` marker for PEP 561 type checker support.
 - `CHANGELOG.md` to track version history.
 - `.gitignore` file.
@@ -111,5 +131,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.1.6] - 2021-01-01
 
 ### Added
+
 - Initial public release.
 - EDGAR client with services: Archives, Companies, CurrentEvents, Datasets, Filings, Issuers, MutualFunds, OwnershipFilings, Series, Submissions, VariableInsuranceProducts, XBRL.

edgar/company.py

@@ -251,3 +251,28 @@ def get_info(self) -> object:
         if raw is None:
             return None
         return CompanyInfo(raw=raw)
+
+    def get_facts(self) -> object:
+        """Returns XBRL company facts as a structured ``Facts`` model.
+
+        Wraps the raw ``xbrl_facts()`` response in a ``Facts``
+        dataclass for convenient access by taxonomy, concept, and unit.
+
+        ### Returns
+        ----
+        Facts | None:
+            A ``Facts`` object, or ``None`` if no data was returned.
+
+        ### Usage
+        ----
+            >>> company = edgar_client.company("AAPL")
+            >>> facts = company.get_facts()
+            >>> facts.get("us-gaap", "Revenue")
+        """
+
+        from edgar.models import Facts
+
+        raw = self.xbrl_facts()
+        if raw is None:
+            return None
+        return Facts(raw=raw)

edgar/models.py

@@ -137,10 +137,7 @@ def recent_filings(self) -> list[dict]:
             return []
 
         num_rows = len(recent[keys[0]])
-        return [
-            {key: recent[key][i] for key in keys}
-            for i in range(num_rows)
-        ]
+        return [{key: recent[key][i] for key in keys} for i in range(num_rows)]
 
     @property
     def recent_submissions(self) -> list[Submission]:
@@ -153,7 +150,9 @@ def recent_submissions(self) -> list[Submission]:
 
     def __repr__(self) -> str:
         ticker_str = ", ".join(self.tickers[:3]) if self.tickers else "N/A"
-        return f"<CompanyInfo name={self.name!r} cik={self.cik!r} tickers={ticker_str!r}>"
+        return (
+            f"<CompanyInfo name={self.name!r} cik={self.cik!r} tickers={ticker_str!r}>"
+        )
 
 
 @dataclass(frozen=True)
@@ -222,3 +221,248 @@ def size(self) -> int:
 
     def __repr__(self) -> str:
         return f"<Submission form={self.form!r} date={self.filing_date!r} accession={self.accession_number!r}>"
+
+
+@dataclass(frozen=True)
+class Fact:
+    """A single XBRL fact data point.
+
+    Each fact represents one reported value for a specific concept,
+    unit, and period.
+
+    ### Usage
+    ----
+        >>> facts = edgar_client.company("AAPL").get_facts()
+        >>> revenue = facts.get("us-gaap", "Revenue")
+        >>> revenue[0].value
+        274515000000
+    """
+
+    raw: dict = field(repr=False)
+
+    @property
+    def end(self) -> str:
+        """The period end date."""
+        return self.raw.get("end", "")
+
+    @property
+    def start(self) -> str:
+        """The period start date (empty for instant facts)."""
+        return self.raw.get("start", "")
+
+    @property
+    def value(self):
+        """The reported numeric value."""
+        return self.raw.get("val")
+
+    @property
+    def accession_number(self) -> str:
+        """The filing accession number."""
+        return self.raw.get("accn", "")
+
+    @property
+    def fiscal_year(self) -> int:
+        """The fiscal year."""
+        return self.raw.get("fy", 0)
+
+    @property
+    def fiscal_period(self) -> str:
+        """The fiscal period (e.g. ``'FY'``, ``'Q1'``, ``'Q2'``)."""
+        return self.raw.get("fp", "")
+
+    @property
+    def form(self) -> str:
+        """The form type that reported this fact (e.g. ``'10-K'``)."""
+        return self.raw.get("form", "")
+
+    @property
+    def filed(self) -> str:
+        """The date the filing was submitted."""
+        return self.raw.get("filed", "")
+
+    @property
+    def frame(self) -> str:
+        """The XBRL frame identifier (e.g. ``'CY2020Q4I'``), if present."""
+        return self.raw.get("frame", "")
+
+    def __repr__(self) -> str:
+        return (
+            f"<Fact end={self.end!r} value={self.value!r}"
+            f" form={self.form!r} fy={self.fiscal_year}>"
+        )
+
+
+@dataclass(frozen=True)
+class Facts:
+    """Structured wrapper around the SEC EDGAR company_facts XBRL response.
+
+    Navigates the deeply nested ``facts`` JSON (4 levels deep) and
+    provides convenient access by taxonomy and concept name.
+
+    ### Usage
+    ----
+        >>> facts = edgar_client.company("AAPL").get_facts()
+        >>> facts.entity_name
+        'Apple Inc.'
+        >>> revenue = facts.get("us-gaap", "Revenues")
+        >>> revenue[0].value
+        274515000000
+        >>> facts.taxonomies
+        ['dei', 'us-gaap']
+        >>> facts.concepts("us-gaap")
+        ['AccountsPayableCurrent', 'AccountsReceivableNetCurrent', ...]
+    """
+
+    raw: dict = field(repr=False)
+
+    @property
+    def cik(self) -> int:
+        """The CIK number."""
+        return self.raw.get("cik", 0)
+
+    @property
+    def entity_name(self) -> str:
+        """The entity name as reported in XBRL."""
+        return self.raw.get("entityName", "")
+
+    @property
+    def taxonomies(self) -> list[str]:
+        """List of taxonomy namespaces present (e.g. ``['dei', 'us-gaap']``)."""
+        return list(self.raw.get("facts", {}).keys())
+
+    def concepts(self, taxonomy: str = "us-gaap") -> list[str]:
+        """List of concept names within a taxonomy.
+
+        ### Parameters
+        ----
+        taxonomy : str (optional, Default=``"us-gaap"``)
+            The taxonomy namespace.
+
+        ### Returns
+        ----
+        list[str]:
+            Sorted list of concept names.
+        """
+        return sorted(self.raw.get("facts", {}).get(taxonomy, {}).keys())
+
+    def get(
+        self,
+        taxonomy: str,
+        concept: str,
+        unit: str | None = None,
+    ) -> list[Fact]:
+        """Retrieves fact data points for a given taxonomy/concept pair.
+
+        ### Parameters
+        ----
+        taxonomy : str
+            The taxonomy namespace (e.g. ``"us-gaap"``, ``"dei"``,
+            ``"ifrs-full"``).
+
+        concept : str
+            The concept tag name (e.g. ``"Revenue"``,
+            ``"AccountsPayableCurrent"``).
+
+        unit : str | None (optional, Default=None)
+            If provided, returns only facts in this unit of measure
+            (e.g. ``"USD"``, ``"shares"``). If ``None``, returns
+            facts from all units combined.
+
+        ### Returns
+        ----
+        list[Fact]:
+            A flat list of ``Fact`` objects, sorted by end date.
+        """
+        concept_data = self.raw.get("facts", {}).get(taxonomy, {}).get(concept, {})
+        if not concept_data:
+            return []
+
+        units_data = concept_data.get("units", {})
+
+        results: list[dict] = []
+        if unit is not None:
+            results = units_data.get(unit, [])
+        else:
+            for entries in units_data.values():
+                results.extend(entries)
+
+        results.sort(key=lambda d: d.get("end", ""))
+        return [Fact(raw=entry) for entry in results]
+
+    def label(self, taxonomy: str, concept: str) -> str:
+        """Returns the human-readable label for a concept.
+
+        ### Parameters
+        ----
+        taxonomy : str
+            The taxonomy namespace.
+
+        concept : str
+            The concept tag name.
+
+        ### Returns
+        ----
+        str:
+            The label string, or empty string if not found.
+        """
+        return (
+            self.raw.get("facts", {})
+            .get(taxonomy, {})
+            .get(concept, {})
+            .get("label", "")
+        )
+
+    def description(self, taxonomy: str, concept: str) -> str:
+        """Returns the description for a concept.
+
+        ### Parameters
+        ----
+        taxonomy : str
+            The taxonomy namespace.
+
+        concept : str
+            The concept tag name.
+
+        ### Returns
+        ----
+        str:
+            The description string, or empty string if not found.
+        """
+        return (
+            self.raw.get("facts", {})
+            .get(taxonomy, {})
+            .get(concept, {})
+            .get("description", "")
+        )
+
+    def units(self, taxonomy: str, concept: str) -> list[str]:
+        """Returns the available units of measure for a concept.
+
+        ### Parameters
+        ----
+        taxonomy : str
+            The taxonomy namespace.
+
+        concept : str
+            The concept tag name.
+
+        ### Returns
+        ----
+        list[str]:
+            List of unit names (e.g. ``["USD", "USD-per-shares"]``).
+        """
+        return list(
+            self.raw.get("facts", {})
+            .get(taxonomy, {})
+            .get(concept, {})
+            .get("units", {})
+            .keys()
+        )
+
+    def __repr__(self) -> str:
+        tax_count = len(self.taxonomies)
+        total = sum(len(self.concepts(t)) for t in self.taxonomies)
+        return (
+            f"<Facts entity={self.entity_name!r} cik={self.cik}"
+            f" taxonomies={tax_count} concepts={total}>"
+        )