notoecd 0.1.3__tar.gz → 0.1.5__tar.gz

{notoecd-0.1.3 → notoecd-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: notoecd
-Version: 0.1.3
+Version: 0.1.5
 Summary: Unofficial library for interacting with the OECD Data Explorer through Python.
 Author-email: Daniel Vegara Balsa <daniel.vegarabalsa@oecd.org>
 License-Expression: MIT
@@ -16,16 +16,16 @@ Dynamic: license-file
 
 ⚠️ **Unofficial package, not endorsed by the OECD.**
 
-A lightweight Python interface for exploring OECD SDMX structures and downloading OECD datasets.  
+A lightweight Python interface for exploring OECD SDMX structures and downloading OECD datasets.
 
 The package provides utilities for:
 
-- Discovering dataset metadata  
-- Searching for relevant datasets using keyword matching  
-- Exploring the structure and code lists of a dataset  
-- Fetching filtered SDMX data directly into a pandas DataFrame  
+- Discovering dataset metadata
+- Searching for relevant datasets using keyword matching
+- Exploring the structure and code lists of a dataset
+- Fetching filtered SDMX data directly into a pandas DataFrame
 
-------------------------------------------------------------
+---
 
 ## Installation
 
@@ -33,7 +33,7 @@ You can install the package by running:
 
     pip install notoecd
 
-------------------------------------------------------------
+---
 
 ## Quick Start
 
@@ -45,30 +45,30 @@ The main functions in this module are:
     get_structure(agencyID, dataflowID) -> Structure
     get_df(agencyID, dataflowID, filters) -> pd.DataFrame
 
-------------------------------------------------------------
+---
 
 ## Searching for datasets
 
 `search_keywords` performs:
 
-- Normalized text matching  
-- Accent-insensitive search  
-- Multi-keyword OR matching  
-- Ranking by number of matched keywords  
+- Normalized text matching
+- Accent-insensitive search
+- Multi-keyword OR matching
+- Ranking by number of matched keywords
 
 Example:
 
-    hits = notoecd.search_keywords(['gross domestic product', 'tl2', 'tl3'])
+    hits = notoecd.search_keywords('gross domestic product', 'tl2', 'tl3')
 
 This returns datasets that mention GDP and regional levels (TL2/TL3). It gives their name, description, and identifiers (agencyID and dataflowID), which we will need for the next step.
 
-------------------------------------------------------------
+---
 
 ## Inspecting dataset structure
 
 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'
 
@@ -87,7 +87,7 @@ This shows all filters and their available values.
 
 This shows the available measures and units used in the dataset.
 
-------------------------------------------------------------
+---
 
 ## Filtering and downloading data
 
@@ -103,12 +103,12 @@ 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.
 
-------------------------------------------------------------
+---
 
 ## Examples
 

{notoecd-0.1.3 → notoecd-0.1.5}/README.md

@@ -2,16 +2,16 @@
 
 ⚠️ **Unofficial package, not endorsed by the OECD.**
 
-A lightweight Python interface for exploring OECD SDMX structures and downloading OECD datasets.  
+A lightweight Python interface for exploring OECD SDMX structures and downloading OECD datasets.
 
 The package provides utilities for:
 
-- Discovering dataset metadata  
-- Searching for relevant datasets using keyword matching  
-- Exploring the structure and code lists of a dataset  
-- Fetching filtered SDMX data directly into a pandas DataFrame  
+- Discovering dataset metadata
+- Searching for relevant datasets using keyword matching
+- Exploring the structure and code lists of a dataset
+- Fetching filtered SDMX data directly into a pandas DataFrame
 
-------------------------------------------------------------
+---
 
 ## Installation
 
@@ -19,7 +19,7 @@ You can install the package by running:
 
     pip install notoecd
 
-------------------------------------------------------------
+---
 
 ## Quick Start
 
@@ -31,30 +31,30 @@ The main functions in this module are:
     get_structure(agencyID, dataflowID) -> Structure
     get_df(agencyID, dataflowID, filters) -> pd.DataFrame
 
-------------------------------------------------------------
+---
 
 ## Searching for datasets
 
 `search_keywords` performs:
 
-- Normalized text matching  
-- Accent-insensitive search  
-- Multi-keyword OR matching  
-- Ranking by number of matched keywords  
+- Normalized text matching
+- Accent-insensitive search
+- Multi-keyword OR matching
+- Ranking by number of matched keywords
 
 Example:
 
-    hits = notoecd.search_keywords(['gross domestic product', 'tl2', 'tl3'])
+    hits = notoecd.search_keywords('gross domestic product', 'tl2', 'tl3')
 
 This returns datasets that mention GDP and regional levels (TL2/TL3). It gives their name, description, and identifiers (agencyID and dataflowID), which we will need for the next step.
 
-------------------------------------------------------------
+---
 
 ## Inspecting dataset structure
 
 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'
 
@@ -73,7 +73,7 @@ This shows all filters and their available values.
 
 This shows the available measures and units used in the dataset.
 
-------------------------------------------------------------
+---
 
 ## Filtering and downloading data
 
@@ -89,12 +89,12 @@ 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.
 
-------------------------------------------------------------
+---
 
 ## Examples
 

{notoecd-0.1.3 → notoecd-0.1.5}/notoecd/__init__.py

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

notoecd-0.1.5/notoecd/calls.py

@@ -0,0 +1,110 @@
+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()
+
+    url = (
+        f"https://sdmx.oecd.org/public/rest/data/"
+        f"{agencyID},{dataflowID},{version}/{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}"
+
+    base_df = _fetch_df(url)
+    return base_df.copy()

{notoecd-0.1.3 → notoecd-0.1.5}/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.3 → notoecd-0.1.5}/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.3 → notoecd-0.1.5}/notoecd.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: notoecd
-Version: 0.1.3
+Version: 0.1.5
 Summary: Unofficial library for interacting with the OECD Data Explorer through Python.
 Author-email: Daniel Vegara Balsa <daniel.vegarabalsa@oecd.org>
 License-Expression: MIT
@@ -16,16 +16,16 @@ Dynamic: license-file
 
 ⚠️ **Unofficial package, not endorsed by the OECD.**
 
-A lightweight Python interface for exploring OECD SDMX structures and downloading OECD datasets.  
+A lightweight Python interface for exploring OECD SDMX structures and downloading OECD datasets.
 
 The package provides utilities for:
 
-- Discovering dataset metadata  
-- Searching for relevant datasets using keyword matching  
-- Exploring the structure and code lists of a dataset  
-- Fetching filtered SDMX data directly into a pandas DataFrame  
+- Discovering dataset metadata
+- Searching for relevant datasets using keyword matching
+- Exploring the structure and code lists of a dataset
+- Fetching filtered SDMX data directly into a pandas DataFrame
 
-------------------------------------------------------------
+---
 
 ## Installation
 
@@ -33,7 +33,7 @@ You can install the package by running:
 
     pip install notoecd
 
-------------------------------------------------------------
+---
 
 ## Quick Start
 
@@ -45,30 +45,30 @@ The main functions in this module are:
     get_structure(agencyID, dataflowID) -> Structure
     get_df(agencyID, dataflowID, filters) -> pd.DataFrame
 
-------------------------------------------------------------
+---
 
 ## Searching for datasets
 
 `search_keywords` performs:
 
-- Normalized text matching  
-- Accent-insensitive search  
-- Multi-keyword OR matching  
-- Ranking by number of matched keywords  
+- Normalized text matching
+- Accent-insensitive search
+- Multi-keyword OR matching
+- Ranking by number of matched keywords
 
 Example:
 
-    hits = notoecd.search_keywords(['gross domestic product', 'tl2', 'tl3'])
+    hits = notoecd.search_keywords('gross domestic product', 'tl2', 'tl3')
 
 This returns datasets that mention GDP and regional levels (TL2/TL3). It gives their name, description, and identifiers (agencyID and dataflowID), which we will need for the next step.
 
-------------------------------------------------------------
+---
 
 ## Inspecting dataset structure
 
 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'
 
@@ -87,7 +87,7 @@ This shows all filters and their available values.
 
 This shows the available measures and units used in the dataset.
 
-------------------------------------------------------------
+---
 
 ## Filtering and downloading data
 
@@ -103,12 +103,12 @@ 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.
 
-------------------------------------------------------------
+---
 
 ## Examples
 

{notoecd-0.1.3 → notoecd-0.1.5}/pyproject.toml

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

notoecd-0.1.3/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()