opendataframework 0.1.0__tar.gz → 0.2.0__tar.gz

{opendataframework-0.1.0 → opendataframework-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opendataframework
-Version: 0.1.0
+Version: 0.2.0
 Summary: Lightweight, config-driven dependency-injection framework for data applications.
 License-Expression: MIT
 License-File: LICENSE
@@ -82,9 +82,7 @@ class User:
 class SQLite:
     def __init__(self, config: Config):
         self.conn = sqlite3.connect(config.sqlite.path)
-        self.conn.execute(
-            "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)"
-        )
+        self.conn.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")
 
 
 @Repository(User)
@@ -281,7 +279,7 @@ No circular dependencies — restructure with a shared third collaborator
 instead.
 
 ```python
-component = project.context.get(UsersApi)   # typed, by class
+component = project.context.get(UsersApi)  # typed, by class
 ```
 
 ## Project
@@ -334,7 +332,7 @@ Project owns everything.
 See [`examples/`](examples/README.md) — small, focused projects each
 isolating one core abstraction.
 
-> For the CLI, UI, MCP server, and chat surface 
+> For the CLI, UI, MCP server, and chat surface
 > built on top of this package, see `odf`.
 
 ---

{opendataframework-0.1.0 → opendataframework-0.2.0}/README.md

@@ -66,9 +66,7 @@ class User:
 class SQLite:
     def __init__(self, config: Config):
         self.conn = sqlite3.connect(config.sqlite.path)
-        self.conn.execute(
-            "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)"
-        )
+        self.conn.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")
 
 
 @Repository(User)
@@ -265,7 +263,7 @@ No circular dependencies — restructure with a shared third collaborator
 instead.
 
 ```python
-component = project.context.get(UsersApi)   # typed, by class
+component = project.context.get(UsersApi)  # typed, by class
 ```
 
 ## Project
@@ -318,7 +316,7 @@ Project owns everything.
 See [`examples/`](examples/README.md) — small, focused projects each
 isolating one core abstraction.
 
-> For the CLI, UI, MCP server, and chat surface 
+> For the CLI, UI, MCP server, and chat surface
 > built on top of this package, see `odf`.
 
 ---

{opendataframework-0.1.0 → opendataframework-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "opendataframework"
-version = "0.1.0"
+version = "0.2.0"
 description = "Lightweight, config-driven dependency-injection framework for data applications."
 authors = [
     {name = "mykytapavlov",email = "mykytapavlov@users.noreply.github.com"}

{opendataframework-0.1.0 → opendataframework-0.2.0}/src/opendataframework/component.py

@@ -6,6 +6,8 @@ injected by the ``Context`` with no execution contract of its own. The
 implement to opt into lifecycle callbacks or inspection tooling.
 """
 
+from collections.abc import Callable
+from dataclasses import dataclass
 from typing import Protocol, runtime_checkable
 
 from opendataframework.namespace import Namespace
@@ -87,6 +89,50 @@ class ChartProtocol(Protocol):
         ...
 
 
+@dataclass
+class McpTool:
+    """One MCP tool a Component exposes, returned from ``mcp_tools()``.
+
+    Attributes:
+        name: The tool's local name — namespaced by whatever builds the
+            tool surface (today, the sibling ``odf`` package's
+            ``McpServer`` prefixes it with the component's kebab-case
+            class name) to avoid collisions with the fixed built-in
+            tools and with other components' tools.
+        description: Human-readable description shown to the MCP client.
+        handler: The bound method implementing the tool call.
+        structured_output: Whether the handler's return value should be
+            reported as structured (JSON) output. ``None`` defers to
+            the MCP server's own default behavior, mirroring how this
+            field is expected to be forwarded verbatim by whatever
+            registers the tool.
+    """
+
+    name: str
+    description: str
+    handler: Callable[..., object]
+    structured_output: bool | None = None
+
+
+@runtime_checkable
+class McpToolsProtocol(Protocol):
+    """Capability interface for a Component's optional custom MCP tools.
+
+    Independent of ``DetailsProtocol``/``ChartProtocol``/
+    ``OnStartProtocol``/``OnStopProtocol``. Never invoked by ``Context``
+    — detected structurally via ``isinstance(instance, McpToolsProtocol)``
+    and consumed on demand by whatever builds an MCP tool surface. (Today,
+    that's the sibling ``odf`` package's ``McpServer``, which registers
+    each returned ``McpTool`` under
+    ``<kebab(cls.__name__)>.<tool.name>``, alongside its six fixed
+    built-in tools.)
+    """
+
+    def mcp_tools(self) -> list[McpTool]:
+        """Return the component's custom MCP tools, in addition to the fixed built-in surface."""
+        ...
+
+
 class Component(Namespace):
     """Decorator that registers a class with the Context for dependency injection.
 

{opendataframework-0.1.0 → opendataframework-0.2.0}/src/opendataframework/config.py

@@ -7,6 +7,7 @@ components declare it like any other constructor dependency.
 """
 
 import tomllib
+from copy import deepcopy
 from pathlib import Path
 
 from opendataframework.utils import normalize
@@ -37,8 +38,14 @@ class Config:
     """
 
     def __init__(self, data: dict) -> None:
-        """Wrap ``data``, a (possibly nested) configuration dict."""
-        self._data = data
+        """Wrap a deep copy of ``data``, a (possibly nested) configuration dict.
+
+        ``data`` is copied rather than stored by reference, so mutating the
+        original dict after construction (e.g. one the caller keeps a
+        reference to and mutates after passing to ``Project.from_dict()``)
+        does not leak through this ``Config``.
+        """
+        self._data = deepcopy(data)
 
     def __getattr__(self, name: str) -> Config | object:
         """Return value by snake_case attribute name, normalised to kebab-case.
@@ -60,10 +67,10 @@ class Config:
         return Config(value) if isinstance(value, dict) else value
 
     def __getitem__(self, key: str) -> Config | object:
-        """Return value by key (any name form accepted).
+        """Return value by key, normalised to kebab-case (any name form accepted).
 
         Args:
-            key: Config key in any supported form.
+            key: Config key (snake_case, kebab-case, or PascalCase).
 
         Returns:
             A ``Config`` wrapping the value if it is a dict, otherwise the
@@ -73,13 +80,13 @@ class Config:
             KeyError: If the key is not present.
         """
         try:
-            value = self._data[key]
+            value = self._data[normalize(key)]
         except KeyError as err:
             raise KeyError(key) from err
         return Config(value) if isinstance(value, dict) else value
 
     def get(self, key: str, default: object = None) -> Config | object | None:
-        """Return value by key, or ``default`` if absent.
+        """Return value by key (any name form accepted), or ``default`` if absent.
 
         If ``default`` is not given and the key is absent, an empty
         ``Config`` is returned instead of ``None``, so callers can safely
@@ -91,7 +98,7 @@ class Config:
             port = cfg.get("port", 5432)    # safe fallback
 
         Args:
-            key: Config key.
+            key: Config key (snake_case, kebab-case, or PascalCase).
             default: Fallback value when the key is not present.
 
         Returns:
@@ -100,7 +107,7 @@ class Config:
             or an empty ``Config`` if the key is absent and no default was
             given.
         """
-        value = self._data.get(key)
+        value = self._data.get(normalize(key))
         if value is None:
             return default if default is not None else Config({})
         return Config(value) if isinstance(value, dict) else value

{opendataframework-0.1.0 → opendataframework-0.2.0}/src/opendataframework/namespace.py

@@ -94,7 +94,14 @@ class Namespace:
             # reveal_type(Classifier) -> type[Classifier], from __call__ below
         """
         if isinstance(_, type):
-            cls._namespace[kebab(_.__name__)] = _
+            key = kebab(_.__name__)
+            if key in cls._namespace:
+                existing = cls._namespace[key]
+                raise ValueError(
+                    f"Duplicate registration for {key!r} in {cls.__name__}: "
+                    f"{existing.__name__} and {_.__name__}"
+                )
+            cls._namespace[key] = _
             return _
         return super().__new__(cls)
 
@@ -129,7 +136,14 @@ class Namespace:
         Returns:
             The original class, unmodified.
         """
-        self.__class__._namespace[self._name or kebab(wrapped.__name__)] = wrapped
+        key = self._name or kebab(wrapped.__name__)
+        if key in self.__class__._namespace:
+            existing = self.__class__._namespace[key]
+            raise ValueError(
+                f"Duplicate registration for {key!r} in {self.__class__.__name__}: "
+                f"{existing.__name__} and {wrapped.__name__}"
+            )
+        self.__class__._namespace[key] = wrapped
         return wrapped
 
     @classmethod

{opendataframework-0.1.0 → opendataframework-0.2.0}/src/opendataframework/project.py

@@ -5,6 +5,8 @@ pure DI lifecycle boundary. It has no knowledge of any UI/CLI/MCP layer
 — those are composed on top of it by consuming packages (e.g. ``odf``).
 """
 
+import importlib
+
 from opendataframework.config import load as load_config
 from opendataframework.context import Context
 
@@ -143,6 +145,14 @@ class Project:
         (default ``"logs"``, relative to the current working directory) —
         see ``opendataframework.logger.LogManager``.
 
+        Imports the module named under ``[project] app`` (if present)
+        before constructing the ``Context`` — equivalent to writing
+        ``import app`` by hand before calling ``from_config``/``from_dict``.
+        That module's own imports (e.g. an ``app/__init__.py`` that imports
+        ``app.components``, ``app.repositories``, ...) are what actually
+        register framework-decorated classes; this just ensures the root
+        import happens before resolution needs it.
+
         Args:
             config: Mapping of configuration values, equivalent to what
                 ``from_config`` would parse from a ``.toml`` file.
@@ -150,6 +160,10 @@ class Project:
         Returns:
             A new ``Project`` configured from the given dict.
 
+        Raises:
+            ImportError: If the module named under ``[project] app`` cannot
+                be imported.
+
         Example:
             ::
 
@@ -159,5 +173,8 @@ class Project:
                     }
                 })
         """
+        app = config.get("project", {}).get("app")
+        if app is not None:
+            importlib.import_module(app)
         log_dir = config.get("project", {}).get("log-dir", "logs")
         return cls(context=Context(config=config, log_dir=log_dir), config=config)

{opendataframework-0.1.0 → opendataframework-0.2.0}/src/opendataframework/view.py

@@ -178,12 +178,12 @@ class ReplayProtocol(Protocol):
     ``ChartProtocol``/``DetailsProtocol`` (``opendataframework.component``) and
     ``DataViewProtocol`` above. (Today, the sibling ``odf`` package's UI is
     what offers a timeline scrubber for this.) A repository with no
-    ``replay_field()`` gets no such affordance — this only matters for
+    ``field()`` gets no such affordance — this only matters for
     ``LocationView``/``VideoView``/``AudioView``-backed repositories; a
     ``TimeseriesView`` repository is always replayable since it already
     names its own timestamp via ``field``.
     """
 
-    def replay_field(self) -> str:
+    def field(self) -> str:
         """Return the entity's timestamp field records can be scrubbed through over time by."""
         ...