notoecd 0.1.4__tar.gz → 0.1.6__tar.gz

{notoecd-0.1.4 → notoecd-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: notoecd
-Version: 0.1.4
+Version: 0.1.6
 Summary: Unofficial library for interacting with the OECD Data Explorer through Python.
 Author-email: Daniel Vegara Balsa <daniel.vegarabalsa@oecd.org>
 License-Expression: MIT
@@ -68,7 +68,7 @@ This returns datasets that mention GDP and regional levels (TL2/TL3). It gives t
 
 Once a dataset is identified, load its SDMX structure:
 
-    dataset = 'Gross domestic product - Regions'
+    # Gross domestic product - Regions
     agencyID = 'OECD.CFE.EDS'
     dataflowID = 'DSD_REG_ECO@DF_GDP'
 
@@ -103,7 +103,7 @@ Keys correspond to SDMX dimensions, values are strings or lists (for multiple va
 
 Fetch the filtered dataset:
 
-    df = notoecd.get_df(agency, dataflow, filters)
+    df = notoecd.get_df(agencyID, dataflowID, filters)
     df.head()
 
 The returned object is a pandas DataFrame containing the requested subset of OECD SDMX data.

{notoecd-0.1.4 → notoecd-0.1.6}/README.md

@@ -54,7 +54,7 @@ This returns datasets that mention GDP and regional levels (TL2/TL3). It gives t
 
 Once a dataset is identified, load its SDMX structure:
 
-    dataset = 'Gross domestic product - Regions'
+    # Gross domestic product - Regions
     agencyID = 'OECD.CFE.EDS'
     dataflowID = 'DSD_REG_ECO@DF_GDP'
 
@@ -89,7 +89,7 @@ Keys correspond to SDMX dimensions, values are strings or lists (for multiple va
 
 Fetch the filtered dataset:
 
-    df = notoecd.get_df(agency, dataflow, filters)
+    df = notoecd.get_df(agencyID, dataflowID, filters)
     df.head()
 
 The returned object is a pandas DataFrame containing the requested subset of OECD SDMX data.

{notoecd-0.1.4 → notoecd-0.1.6}/notoecd/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.1.4"
+__version__ = "0.1.6"
 
 from .calls import get_df
 from .structure import get_structure

notoecd-0.1.6/notoecd/calls.py

@@ -0,0 +1,117 @@
+import pandas as pd
+from functools import lru_cache
+from typing import Union, Optional
+from .structure import get_structure
+
+@lru_cache(maxsize=64)
+def _fetch_df(url: str) -> pd.DataFrame:
+    return pd.read_csv(url, storage_options={"User-Agent": "Mozilla/5.0"})
+
+
+def _clean(s: str) -> str: 
+    return str(s).strip().lower()
+
+
+def _clean_dict(d: dict) -> dict:
+    out = {}
+    for k, v in d.items():
+        k = _clean(k)
+        if isinstance(v, (list, tuple, set)):
+            out[k] = [_clean(x) for x in v]
+        else:
+            out[k] = _clean(v)
+    return out
+
+
+def _build_filter_expression(
+    agencyID: str,
+    dataflowID: str,
+    filters: dict,
+) -> str:
+    """
+    Builds a valid OECD SDMX filter expression from a dictionary.
+    
+    Args:
+        agencyID (str): The data provider agency identifier.
+        dataflowID (str): The dataflow identifier within the agency.
+        filters (dict): Dictionary with dimension names as keys and 
+            either codes or labels as values.
+
+    Returns 
+        str: A valid OECD SDMX filter expression.
+    """
+    s = get_structure(agencyID, dataflowID)
+    filters = _clean_dict(filters)
+    
+    parts = []
+    for dim in s.toc.title:
+        dim_key = _clean(dim)
+
+        if dim_key in filters:
+            val = filters[dim_key]
+            concepts = _clean_dict(s.explain_vals(dim_key))
+            rev = {v: k for k, v in concepts.items()}
+
+            if isinstance(val, str): 
+                val = [val]
+            val = [_clean(v) for v in val]
+            
+            for i, v in enumerate(val):
+                if v in concepts: continue
+                if v in rev: val[i] = rev[v]
+                else: raise ValueError(f"Invalid value '{v}' for dimension '{dim_key}'. ")
+
+            parts.append("+".join(val))
+        else:
+            parts.append("")
+    return ".".join(parts).upper()
+
+
+def get_df(
+    agencyID: str,
+    dataflowID: str,
+    filters: Union[str, dict] = "",
+    version: str = "",
+    startYear: Optional[int] = None,
+    endYear: Optional[int] = None,
+) -> pd.DataFrame:
+    """
+    Fetch data from the OECD SDMX API and return it as a pandas DataFrame.
+
+    Args:
+        agencyID (str): The data provider agency identifier.
+        dataflowID (str): The dataflow identifier within the agency.
+        filters (Union[str, dict], optional): Either a preformatted SDMX filter
+            string or a dictionary of filters.
+        version (str, optional): The dataflow version. Use an empty string for
+            the latest version.
+        startYear (int, optional): Start year (inclusive).
+        endYear (int, optional): End year (inclusive).
+
+    Returns:
+        pd.DataFrame: The resulting dataset.
+    """
+
+    if isinstance(filters, dict):
+        filter_expression = _build_filter_expression(agencyID, dataflowID, filters)
+    else:
+        filter_expression = _clean(filters).upper()
+
+    def build_url(ver: str) -> str:
+        url = (
+            f"https://sdmx.oecd.org/public/rest/data/"
+            f"{agencyID},{dataflowID},{ver}/{filter_expression}"
+            f"?dimensionAtObservation=AllDimensions&format=csvfile"
+        )
+        if startYear is not None: url += f"&startPeriod={startYear}"
+        if endYear is not None: url += f"&endPeriod={endYear}"
+        return url
+
+    versions_to_try = [version] if version else ["", "2", "1"]
+    last_err: Exception | None = None
+
+    for ver in versions_to_try:
+        try: return _fetch_df(build_url(ver)).copy()
+        except Exception as e: last_err = e
+
+    raise last_err

{notoecd-0.1.4 → notoecd-0.1.6}/notoecd/datasets.py

@@ -68,7 +68,7 @@ def search_keywords(*keywords: str) -> pd.DataFrame:
     Searches OECD datasets for a set of keywords.
 
     Args:
-        keywords (str | list[str]): Single keyword or list of keywords. Acts as OR.
+        *keywords (str): One or more keywords. Acts as OR.
 
     Returns:
         pd.DataFrame: Matching rows.
@@ -89,13 +89,13 @@ def search_keywords(*keywords: str) -> pd.DataFrame:
             )
         )
 
-    # Combined normalized text for each row
     text = (
         datasets["name"].fillna("").astype(str)
         + " "
         + datasets["description"].fillna("").astype(str)
     )
     text_norm = _normalize_series(text)
+    name_norm = _normalize_series(datasets["name"])
 
     def _normalize_kw(kw: str) -> str:
         kw = unicodedata.normalize("NFKD", kw.lower())
@@ -108,8 +108,9 @@ def search_keywords(*keywords: str) -> pd.DataFrame:
 
     for kw in norm_keywords:
         m = text_norm.str.contains(kw, na=False, regex=False)
+        mt = name_norm.str.contains(kw, na=False, regex=False)
         overall_mask |= m
-        score = score.add(m.astype("int8"), fill_value=0)
+        score = score.add(m.astype("int8"), fill_value=0) + mt.astype("int8")
 
     result = datasets.loc[overall_mask].copy()
     result["_match_score"] = score.loc[overall_mask]

{notoecd-0.1.4 → notoecd-0.1.6}/notoecd/structure.py

@@ -138,7 +138,11 @@ class Structure():
             print(f"Could not find explanation for {unclean_values}")
 
         return {i:explanation[i] for i in clean_values}
+    
+    def explain_columns(self, df:pd.DataFrame) -> dict:
+        dim_dict = self.concepts['DIMENSIONS']
+        return {i: dim_dict[i] for i in df.columns if i in dim_dict}
 
-@lru_cache(maxsize=128)
+@lru_cache(maxsize=64)
 def get_structure(agencyID: str, dataflowID: str) -> Structure:
     return Structure(agencyID, dataflowID)

{notoecd-0.1.4 → notoecd-0.1.6}/notoecd.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: notoecd
-Version: 0.1.4
+Version: 0.1.6
 Summary: Unofficial library for interacting with the OECD Data Explorer through Python.
 Author-email: Daniel Vegara Balsa <daniel.vegarabalsa@oecd.org>
 License-Expression: MIT
@@ -68,7 +68,7 @@ This returns datasets that mention GDP and regional levels (TL2/TL3). It gives t
 
 Once a dataset is identified, load its SDMX structure:
 
-    dataset = 'Gross domestic product - Regions'
+    # Gross domestic product - Regions
     agencyID = 'OECD.CFE.EDS'
     dataflowID = 'DSD_REG_ECO@DF_GDP'
 
@@ -103,7 +103,7 @@ Keys correspond to SDMX dimensions, values are strings or lists (for multiple va
 
 Fetch the filtered dataset:
 
-    df = notoecd.get_df(agency, dataflow, filters)
+    df = notoecd.get_df(agencyID, dataflowID, filters)
     df.head()
 
 The returned object is a pandas DataFrame containing the requested subset of OECD SDMX data.

{notoecd-0.1.4 → notoecd-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "notoecd"
-version = "0.1.4"
+version = "0.1.6"
 description = "Unofficial library for interacting with the OECD Data Explorer through Python."
 readme = "README.md"
 license = "MIT"

notoecd-0.1.4/notoecd/calls.py

@@ -1,57 +0,0 @@
-import pandas as pd
-from typing import Union
-from functools import lru_cache
-from .structure import get_structure
-
-@lru_cache(maxsize=64)
-def _fetch_df(url: str) -> pd.DataFrame:
-    return pd.read_csv(url, storage_options={"User-Agent": "Mozilla/5.0"})
-
-
-def _clean(s: str) -> str: 
-    return str(s).strip().lower()
-
-
-def _build_filter_expression(
-    agencyID: str,
-    dataflowID: str,
-    filters: dict,
-) -> str:
-    
-    s = get_structure(agencyID, dataflowID)
-    filters = {_clean(k): v for k, v in filters.items()}
-
-    parts = []
-    for dim in s.toc.title:
-        dim_key = _clean(dim)
-        if dim_key in filters:
-            val = filters[dim_key]
-            if isinstance(val, str):
-                val = [val]
-            parts.append("+".join(_clean(v) for v in val))
-        else:
-            parts.append("")
-
-    return ".".join(parts).upper()
-
-
-def get_df(
-    agencyID: str,
-    dataflowID: str,
-    filters: Union[str, dict] = "",
-    version: str = "",
-) -> pd.DataFrame:
-    
-    if isinstance(filters, dict):
-        filter_expression = _build_filter_expression(agencyID, dataflowID, filters)
-    else:
-        filter_expression = _clean(filters).upper()
-
-    url = (
-        f"https://sdmx.oecd.org/public/rest/data/"
-        f"{agencyID},{dataflowID},{version}/{filter_expression}"
-        "?dimensionAtObservation=AllDimensions&format=csvfile"
-    )
-
-    base_df = _fetch_df(url)
-    return base_df.copy()