Sources

Most applications should construct ICD10KnowledgeBase instead of instantiating a provider directly. Providers are public extension points for applications that need a custom material source.

cms_icd.sources.MaterialProvider

Abstract provider of local paths for individual ICD materials.

paths abstractmethod

paths(system: str, material: str) -> tuple[Path, ...]

Return local files needed for a system/material pair.

Source code in src/cms_icd/sources.py

@abstractmethod
def paths(self, system: str, material: str) -> tuple[Path, ...]:
    """Return local files needed for a system/material pair."""

cms_icd.sources.CMSProvider

CMSProvider(release: Release, *, service_date: date | None = None, cache_dir: str | Path | None = None, fallback: str | None = None, offline: bool = False, session: Session | None = None)

Lazily resolve and cache materials from official CMS catalog pages.

Exact revisions represent snapshots: each material resolves to the latest artifact effective on or before the requested revision. The requested date must itself be a revision advertised by CMS unless an explicit fallback is enabled.

Source code in src/cms_icd/sources.py

def __init__(
    self,
    release: Release,
    *,
    service_date: date | None = None,
    cache_dir: str | Path | None = None,
    fallback: str | None = None,
    offline: bool = False,
    session: requests.Session | None = None,
) -> None:
    self.release = release
    self.service_date = service_date
    self.cache_dir = (
        Path(cache_dir) if cache_dir is not None else default_cache_dir()
    )
    self.fallback = fallback
    self.offline = offline
    self._session = session or requests.Session()
    self._catalog: tuple[CatalogEntry, ...] | None = None

cms_icd.sources.DirectoryProvider

DirectoryProvider(directory: str | Path, release: Release)

Discover CMS-format files in an existing directory.

Source code in src/cms_icd/sources.py

def __init__(self, directory: str | Path, release: Release) -> None:
    self.directory = Path(directory)
    if not self.directory.is_dir():
        raise FileNotFoundError(
            f"ICD material directory does not exist: {self.directory}"
        )
    self.release = release

cms_icd.sources.CatalogEntry dataclass

CatalogEntry(system: str, material: str, fiscal_year: int, release_date: date, label: str, url: str, page_url: str)

One downloadable material advertised by CMS.

cms_icd.sources.fiscal_year_for

fiscal_year_for(value: date) -> int

Return the CMS fiscal year containing a date.

Examples:

>>> fiscal_year_for(date(2025, 9, 30))
2025
>>> fiscal_year_for(date(2025, 10, 1))
2026

Source code in src/cms_icd/sources.py

def fiscal_year_for(value: date) -> int:
    """Return the CMS fiscal year containing a date.

    Examples:
        >>> fiscal_year_for(date(2025, 9, 30))
        2025
        >>> fiscal_year_for(date(2025, 10, 1))
        2026
    """
    return value.year + 1 if (value.month, value.day) >= (10, 1) else value.year

cms_icd.sources.refresh_cms_catalog

refresh_cms_catalog(*, cache_dir: str | Path | None = None) -> None

Fetch and atomically replace the cached CMS material catalog.

Normal online constructors reuse a valid cached catalog indefinitely. Call this function when newly advertised CMS releases should become discoverable.

Source code in src/cms_icd/sources.py

def refresh_cms_catalog(*, cache_dir: str | Path | None = None) -> None:
    """Fetch and atomically replace the cached CMS material catalog.

    Normal online constructors reuse a valid cached catalog indefinitely. Call this
    function when newly advertised CMS releases should become discoverable.
    """
    selected = Path(cache_dir) if cache_dir is not None else default_cache_dir()
    _shared_catalog(
        selected,
        offline=False,
        session=requests.Session(),
        refresh=True,
    )