cbrkit 0.3.1__tar.gz → 0.3.2__tar.gz

{cbrkit-0.3.1 → cbrkit-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cbrkit
-Version: 0.3.1
+Version: 0.3.2
 Summary: Customizable Case-Based Reasoning (CBR) toolkit for Python with a built-in API and CLI.
 Home-page: https://wi2trier.github.io/cbrkit/
 License: MIT
@@ -104,7 +104,7 @@ The following modules are part of CBRkit:
 CBRkit is fully typed, so IDEs like VSCode and PyCharm can provide autocompletion and type checking.
 We will explain all modules and their basic usage in the following sections.
 
-### Loading Cases
+### Loading Cases and Queries
 
 The first step is to load cases and queries.
 We provide predefined functions for the most common formats like CSV, JSON, and XML.
@@ -119,9 +119,36 @@ df = pd.read_csv("path/to/cases.csv")
 cases = cbrkit.loaders.dataframe(df)
 ```
 
-Queries can either be loaded using the same loader functions or constructed manually.
+When dealing with formats like JSON, the files can be loaded directly:
 
 ```python
+cases = cbrkit.loaders.json("path/to/cases.json")
+```
+
+Queries can either be loaded using the same loader functions.
+CBRkit expects the type of the queries to match the type of the cases.
+
+```python
+ # for pandas
 queries = cbrkit.loaders.dataframe(pd.read_csv("path/to/queries.csv"))
+# for json
+queries = cbrkit.loaders.json("path/to/queries.json")
 ```
 
+In case your query collection only contains a single query, you can use the `singleton` function to extract it.
+
+```python
+query = cbrkit.singleton(queries)
+```
+
+Alternatively, you can also create a query directly in Python:
+
+```python
+# for pandas
+query = pd.Series({"name": "John", "age": 25})
+# for json
+query = {"name": "John", "age": 25}
+```
+
+### Similarity Measures and Aggregation
+

{cbrkit-0.3.1 → cbrkit-0.3.2}/README.md

@@ -55,7 +55,7 @@ The following modules are part of CBRkit:
 CBRkit is fully typed, so IDEs like VSCode and PyCharm can provide autocompletion and type checking.
 We will explain all modules and their basic usage in the following sections.
 
-### Loading Cases
+### Loading Cases and Queries
 
 The first step is to load cases and queries.
 We provide predefined functions for the most common formats like CSV, JSON, and XML.
@@ -70,8 +70,35 @@ df = pd.read_csv("path/to/cases.csv")
 cases = cbrkit.loaders.dataframe(df)
 ```
 
-Queries can either be loaded using the same loader functions or constructed manually.
+When dealing with formats like JSON, the files can be loaded directly:
 
 ```python
+cases = cbrkit.loaders.json("path/to/cases.json")
+```
+
+Queries can either be loaded using the same loader functions.
+CBRkit expects the type of the queries to match the type of the cases.
+
+```python
+ # for pandas
 queries = cbrkit.loaders.dataframe(pd.read_csv("path/to/queries.csv"))
+# for json
+queries = cbrkit.loaders.json("path/to/queries.json")
 ```
+
+In case your query collection only contains a single query, you can use the `singleton` function to extract it.
+
+```python
+query = cbrkit.singleton(queries)
+```
+
+Alternatively, you can also create a query directly in Python:
+
+```python
+# for pandas
+query = pd.Series({"name": "John", "age": 25})
+# for json
+query = {"name": "John", "age": 25}
+```
+
+### Similarity Measures and Aggregation

{cbrkit-0.3.1 → cbrkit-0.3.2}/cbrkit/__init__.py

@@ -5,12 +5,14 @@
 
 """
 
-from . import global_sim, loaders, retrieval, sim, typing
 
-__all__ = (
+from . import global_sim, helpers, loaders, retrieval, sim, typing
+
+__all__ = [
     "loaders",
     "sim",
     "global_sim",
     "typing",
     "retrieval",
-)
+    "helpers",
+]

{cbrkit-0.3.1 → cbrkit-0.3.2}/cbrkit/global_sim/_aggregate.py

@@ -2,7 +2,7 @@ import statistics
 from collections.abc import Mapping, Sequence
 from typing import Literal
 
-from cbrkit.sim._helpers import unpack_sim
+from cbrkit.helpers import unpack_sim
 from cbrkit.typing import (
     AggregatorFunc,
     AnyFloat,

{cbrkit-0.3.1 → cbrkit-0.3.2}/cbrkit/global_sim/_attribute_value.py

@@ -5,7 +5,7 @@ from typing import Any, Generic
 
 import pandas as pd
 
-from cbrkit.sim import sim2map
+from cbrkit.helpers import sim2map
 from cbrkit.typing import (
     AggregatorFunc,
     AnySimFunc,

{cbrkit-0.3.1 → cbrkit-0.3.2}/cbrkit/global_sim/graph/_astar.py

@@ -16,7 +16,7 @@ from cbrkit.global_sim.graph._model import (
     NodeData,
     NodeKey,
 )
-from cbrkit.sim._helpers import unpack_sims
+from cbrkit.helpers import unpack_sims
 from cbrkit.typing import Casebase, FloatProtocol, KeyType, SimPairFunc, SimType
 
 logger = logging.getLogger(__name__)

cbrkit-0.3.1/cbrkit/sim/_helpers.py → cbrkit-0.3.2/cbrkit/helpers.py

@@ -1,5 +1,5 @@
 from abc import ABC
-from collections.abc import Iterable, Mapping, Sequence
+from collections.abc import Collection, Iterable, Mapping, Sequence
 from inspect import signature as inspect_signature
 from typing import Any, cast
 
@@ -22,9 +22,41 @@ __all__ = [
     "unpack_sim",
     "unpack_sims",
     "AbstractFloat",
+    "singleton",
 ]
 
 
+def singleton(x: Mapping[Any, ValueType] | Collection[ValueType]) -> ValueType:
+    """
+    Return the only element of the input, or raise an error if there are multiple elements.
+
+    Args:
+        x: The input collection or mapping.
+
+    Returns:
+        The only element of the input.
+
+    Examples:
+        >>> singleton([1])
+        1
+        >>> singleton({1: "a"})
+        'a'
+
+    Raises:
+        ValueError: If the input has more than one element.
+        TypeError: If the input is not a collection or mapping.
+    """
+    if len(x) != 1:
+        raise ValueError(f"Expected exactly one element, but got {len(x)}")
+
+    if isinstance(x, Mapping):
+        return next(iter(x.values()))
+    elif isinstance(x, Collection):
+        return next(iter(x))
+    else:
+        raise TypeError(f"Expected a Mapping or Collection, but got {type(x)}")
+
+
 def dist2sim(distance: float) -> float:
     """Convert a distance to a similarity.
 

{cbrkit-0.3.1 → cbrkit-0.3.2}/cbrkit/retrieval.py

@@ -2,8 +2,8 @@ from collections.abc import Callable, Collection, Mapping, Sequence
 from dataclasses import dataclass
 from typing import Any, Generic
 
+from cbrkit.helpers import sim2map, unpack_sim
 from cbrkit.loaders import python as load_python
-from cbrkit.sim._helpers import sim2map, unpack_sim
 from cbrkit.typing import (
     AnySimFunc,
     Casebase,

cbrkit-0.3.2/cbrkit/sim/__init__.py

@@ -0,0 +1,9 @@
+from . import collections, generic, numeric, strings, taxonomy
+
+__all__ = [
+    "collections",
+    "generic",
+    "numeric",
+    "strings",
+    "taxonomy",
+]

{cbrkit-0.3.1 → cbrkit-0.3.2}/cbrkit/sim/collections.py

@@ -1,7 +1,7 @@
 from collections.abc import Collection, Set
 from typing import Any
 
-from cbrkit.sim._helpers import dist2sim
+from cbrkit.helpers import dist2sim
 from cbrkit.typing import SimPairFunc
 
 __all__ = ["jaccard"]

{cbrkit-0.3.1 → cbrkit-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "cbrkit"
-version = "0.3.1"
+version = "0.3.2"
 description = "Customizable Case-Based Reasoning (CBR) toolkit for Python with a built-in API and CLI."
 authors = ["Mirko Lenz <mirko@mirkolenz.com>"]
 license = "MIT"

cbrkit-0.3.1/cbrkit/sim/__init__.py

@@ -1,16 +0,0 @@
-from . import collections, generic, numeric, strings, taxonomy
-from ._helpers import AbstractFloat, dist2sim, sim2map, sim2seq, unpack_sim, unpack_sims
-
-__all__ = [
-    "collections",
-    "generic",
-    "numeric",
-    "strings",
-    "taxonomy",
-    "dist2sim",
-    "sim2map",
-    "sim2seq",
-    "unpack_sim",
-    "unpack_sims",
-    "AbstractFloat",
-]