Complete rewrite

Author: serg-shkatula

.gitignore

@@ -169,3 +169,6 @@ cython_debug/
 
 # PyPI configuration file
 .pypirc
+
+# Misk
+.DS_Store

LICENSE

@@ -1,27 +1,80 @@
-# micro env
+# microenv
 
-Minimal implementation of environment with different data types represented as a tree.
+[![PyPI version](https://img.shields.io/pypi/v/microenv.svg)](https://pypi.org/project/microenv/)
+[![GitHub release](https://img.shields.io/github/v/release/ceil-python/microenv.svg?logo=github)](https://github.com/ceil-python/microenv/releases)
+[![License](https://img.shields.io/pypi/l/supply-demand.svg)](LICENSE)
+
+A minimal Python environment abstraction with privacy controls and async “next” subscriptions.
+
+## Installation
+
+```bash
+pip install microenv
+```
+
+or
+
+```bash
+python -m pip install microenv
+```
+
+or
+
+```bash
+python3 -m pip install microenv
+```
+
+## Quickstart
 
 ```python
-from env import MicroEnv
-
-if __name__ == "__main__":
-    def test():
-        return 2
-    micro_env = MicroEnv(
-        {"prop_a": 1, "prop_b": 2, "prop_c": test},
-        {
-            "id": "my_env",
-            "children": [
-                {
-                    "prop_d": {"type": "int", "value": 1},
-                },
-                {"id": "my_env1"},
-            ],
-        },
-    )
-    micro_env.set("prop_a", 10)
-    micro_env.get("prop_a")
-    micro_env.set("prop_d", test, "root/my_env1")
-    micro_env.get("prop_d", "root/my_env1")
-```
+import asyncio
+from microenv import microenv
+
+# Define initial data and optional descriptor
+data = {"public": 1, "secret": "s3cr3t"}
+descriptor = {
+    "children": [
+        {"key": "public", "type": "number"},
+        {"key": "secret", "type": "string", "private": True},
+    ]
+}
+
+# Create the environment
+env = microenv(obj=data, descriptor=descriptor)
+face = env.face
+
+# Basic get / set via the face
+print(face.public)         # → 1
+face.public = 42
+print(env.data["public"])  # → 42
+
+# Privacy: direct .secret bypasses privacy checks on the face
+print(face.secret)         # → "s3cr3t"
+face.secret = "new!"
+print(env.data["secret"])  # → "new!"
+
+# Async “next” subscription: await the next update to a key
+async def wait_for_update():
+    fut = env.get("public", next_=True)
+    print("waiting for next public…")
+    val = await fut
+    print("new public value:", val)
+
+# Schedule waiter and then update
+loop = asyncio.get_event_loop()
+loop.create_task(wait_for_update())
+loop.call_soon(lambda: setattr(face, "public", 99))
+loop.run_forever()
+```
+
+## API
+
+- `microenv(obj: dict, descriptor: dict = None) → MicroEnv`
+  - `env.face` : proxy for getting/setting properties.
+  - `env.get(key, caller=None, next_=False)` : synchronous read or, if `next_=True`, a Future resolving on next `set`.
+  - `env.set(key, value, caller=None)` : update a property, resolving any pending “next” futures.
+
+## License
+
+This project is licensed under the MIT License.  
+See [LICENSE](https://github.com/ceil-python/microenv/blob/main/LICENSE) for details.

README.md

@@ -0,0 +1,18 @@
+[project]
+name = "microenv"
+version = "0.0.4"
+authors = [{ name = "Sergey Shkatula", email = "[email protected]" }]
+description = "Functional dependency paradigm"
+keywords = ["micro", "env", "environment", "microenv"]
+requires-python = ">=3.7"
+license = "MIT"
+
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/MicroEnv"]
+
+[project.urls]
+Homepage = "https://github.com/ceil-python/microenv"

__init__.py

@@ -0,0 +1,3 @@
+from .microenv import microenv
+
+__version__ = "0.0.4"

env.py

@@ -0,0 +1,150 @@
+import inspect
+
+try:
+    import uasyncio as asyncio
+except ModuleNotFoundError:
+    import asyncio
+
+
+class MicroEnv:
+    def __init__(
+        self,
+        descriptor,
+        face,
+        data,
+        get,
+        set_,
+        _awaiters,
+        _get_awaiter,
+        _pending_get,
+    ):
+        self.descriptor = descriptor
+        self.face = face
+        self.data = data
+        self.get = get
+        self.set = set_
+        self._awaiters = _awaiters
+        self._get_awaiter = _get_awaiter
+        self._pending_get = _pending_get
+
+
+class Awaiter:
+    def __init__(self):
+        self._future = asyncio.get_event_loop().create_future()
+
+    def resolve(self, value):
+        if not self._future.done():
+            self._future.set_result(value)
+
+    def reject(self, reason):
+        if not self._future.done():
+            self._future.set_exception(
+                reason if isinstance(reason, Exception) else Exception(str(reason))
+            )
+
+    @property
+    def promise(self):
+        return self._future
+
+    def then(self, cb):
+        self._future.add_done_callback(lambda fut: cb(fut.result()))
+
+
+def microenv(obj=None, descriptor=None, overrides=None):
+    obj = obj or {}
+    descriptor = descriptor or {}
+    overrides = overrides or {}
+
+    def infer_type(v):
+        if v is None:
+            return "null"
+        elif isinstance(v, str):
+            return "string"
+        elif isinstance(v, bool):
+            return "boolean"
+        elif isinstance(v, (int, float)):
+            return "number"
+        elif isinstance(v, list):
+            return "array"
+        elif isinstance(v, dict):
+            return "object"
+        elif hasattr(v, "__await__"):
+            return "promise"
+        else:
+            return "unknown"
+
+    if "children" not in descriptor:
+        children = [
+            {
+                "key": k,
+                "type": ("unknown" if k not in obj else infer_type(obj[k])),
+            }
+            for k in obj
+        ]
+        descriptor = {
+            "key": "environment",
+            "type": "environment",
+            **descriptor,
+            "children": children,
+        }
+    children_map = {c["key"]: c for c in descriptor.get("children", [])}
+    _awaiters = {}
+    _pending_get = {}
+
+    def _get_awaiter(key):
+        if key not in _awaiters:
+            _awaiters[key] = Awaiter()
+        return _awaiters[key]
+
+    def get(key, caller=None, next_=False):
+        child_descriptor = children_map.get(key)
+        if not child_descriptor:
+            raise KeyError(f'microenv: get non-existent property "{key}"')
+        # privacy: only matter if the key is private and a caller is supplied
+        if child_descriptor.get("private") and caller:
+            raise PermissionError(f'microenv: get private property "{key}"')
+        # async “next” request
+        if next_:
+            return _pending_get.setdefault(key, _get_awaiter(key).promise)
+        # otherwise just return the current value
+        return obj.get(key)
+
+    def set_(key, value, caller=None):
+        child_descriptor = children_map.get(key)
+        if not child_descriptor:
+            raise KeyError(f'microenv: set non-existent property "{key}"')
+        if caller and child_descriptor.get("private"):
+            raise PermissionError(f'microenv: set private property "{key}"')
+        if key in _awaiters:
+            _awaiters[key].resolve(value)
+        obj[key] = value
+        return value
+
+    class Face:
+        __slots__ = ()
+
+        def __getattr__(self, key):
+            v = get(key)
+            if callable(v):
+                return lambda payload, caller=None: v(payload, caller)
+            return v
+
+        def __setattr__(self, key, value):
+            set_(key, value)
+
+        def __getitem__(self, key):
+            return self.__getattr__(key)
+
+        def __setitem__(self, key, value):
+            self.__setattr__(key, value)
+
+    return MicroEnv(
+        descriptor=descriptor,
+        face=Face(),
+        data=obj,
+        get=get,
+        set_=set_,
+        _awaiters=_awaiters,
+        _get_awaiter=_get_awaiter,
+        _pending_get=_pending_get,
+    )