sg-observable 0.1.0a0__tar.gz

sg_observable-0.1.0a0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include tests *.py *.txt

sg_observable-0.1.0a0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: sg-observable
+Version: 0.1.0a0
+Summary: Typed observable fields with conversion and change notifications
+License: MIT
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sg-metacore>=0.1.0a1
+Requires-Dist: numpy
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pyright>=1.1.411; extra == "dev"
+Dynamic: license-file
+
+# observable
+
+Observable fields with conversion, access policies, and change notifications.
+Requires Python 3.13 or newer.
+
+## Installation
+
+Install the `sg-observable` package from PyPI:
+
+```bash
+python -m pip install sg-observable
+```
+
+Pip also installs its dependencies: `sg-metacore` from PyPI and NumPy.
+
+## Usage
+
+```python
+from observable.observable import Observable, ObservableField, auto_field
+
+class Counter(Observable):
+    value: ObservableField[int, str] = auto_field(default=0)
+
+counter = Counter()
+counter.value = "42"       # Writes accept str and convert to int.
+assert counter.value == 42 # Reads return int.
+```
+
+## Runtime and typing
+
+`src/observable/observable.py` contains the implementation and its public type
+annotations, including descriptor overloads and the types of field decorators.
+
+`auto_field()` is intended for annotated declarations in an `Observable` class.
+At runtime it returns an `AutoField` configuration that the metaclass replaces
+with an `ObservableField`. Its return annotation describes that resulting
+descriptor, with a localized cast in the factory to account for the metaclass
+transformation and preserve the field's read and write types.
+Use `AutoField` directly when working with a configuration outside a class body.
+
+The wheel includes a `py.typed` marker so type checkers use the annotations in
+the implementation. Existing comments and TODOs remain in the implementation.
+
+## Development
+
+From the `observable` project directory, install the development dependencies
+and run the checks. MetaCore is installed as the `sg-metacore` PyPI dependency.
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pyright --project pyproject.toml
+python -m pytest
+```
+
+The tests cover runtime behavior and rejected type errors.
+Static examples under `tests/typing/` verify descriptor inference and
+callback signatures.

sg_observable-0.1.0a0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sg-observable"
+version = "0.1.0a0"
+description = "Typed observable fields with conversion and change notifications"
+readme = "readme.md"
+license = {text = "MIT"}
+requires-python = ">=3.13"
+dependencies = ["sg-metacore>=0.1.0a1", "numpy"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pyright>=1.1.411"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["observable", "observable.*"]
+namespaces = false
+
+[tool.setuptools.package-data]
+observable = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.pyright]
+include = ["src", "tests"]
+extraPaths = ["src"]
+typeCheckingMode = "standard"
+pythonVersion = "3.13"

sg_observable-0.1.0a0/readme.md

@@ -0,0 +1,57 @@
+# observable
+
+Observable fields with conversion, access policies, and change notifications.
+Requires Python 3.13 or newer.
+
+## Installation
+
+Install the `sg-observable` package from PyPI:
+
+```bash
+python -m pip install sg-observable
+```
+
+Pip also installs its dependencies: `sg-metacore` from PyPI and NumPy.
+
+## Usage
+
+```python
+from observable.observable import Observable, ObservableField, auto_field
+
+class Counter(Observable):
+    value: ObservableField[int, str] = auto_field(default=0)
+
+counter = Counter()
+counter.value = "42"       # Writes accept str and convert to int.
+assert counter.value == 42 # Reads return int.
+```
+
+## Runtime and typing
+
+`src/observable/observable.py` contains the implementation and its public type
+annotations, including descriptor overloads and the types of field decorators.
+
+`auto_field()` is intended for annotated declarations in an `Observable` class.
+At runtime it returns an `AutoField` configuration that the metaclass replaces
+with an `ObservableField`. Its return annotation describes that resulting
+descriptor, with a localized cast in the factory to account for the metaclass
+transformation and preserve the field's read and write types.
+Use `AutoField` directly when working with a configuration outside a class body.
+
+The wheel includes a `py.typed` marker so type checkers use the annotations in
+the implementation. Existing comments and TODOs remain in the implementation.
+
+## Development
+
+From the `observable` project directory, install the development dependencies
+and run the checks. MetaCore is installed as the `sg-metacore` PyPI dependency.
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pyright --project pyproject.toml
+python -m pytest
+```
+
+The tests cover runtime behavior and rejected type errors.
+Static examples under `tests/typing/` verify descriptor inference and
+callback signatures.

sg_observable-0.1.0a0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sg_observable-0.1.0a0/src/observable/observable.py

@@ -0,0 +1,582 @@
+"""
+MIT License
+
+Copyright (c) 2026 Sébastien Gachoud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+-------------------------------------------------------------------------------
+
+Author: Sébastien Gachoud
+Created: 2026-10-05
+Description: This module provides observable fields and change notifications.
+🦙
+"""
+
+from __future__ import annotations
+
+__author__ = "Sébastien Gachoud"
+__license__ = "MIT"
+
+import sys
+from copy import copy
+from dataclasses import dataclass
+from enum import IntFlag
+from enum import auto as e_auto
+from typing import (
+    Any,
+    Callable,
+    Self,
+    TypeVar,
+    get_args,
+    get_origin,
+    cast,
+    overload,
+)
+
+import numpy as np
+
+from metacore import TracedException, annotation_registry
+from metacore.annotations import AnnotationsRegistry
+from metacore.typing import resolve_annotation_types
+
+type Observer = Callable[..., Any]
+
+
+class ObservableFieldError(TracedException):
+    """Base error for observable field definitions and access."""
+
+
+class UninitializedError(ObservableFieldError):
+    """A field has neither a stored value nor a default."""
+
+
+class MemberDefinitionError(ObservableFieldError):
+    """An observable member has an invalid definition."""
+
+
+class TypeFormatError(ObservableFieldError):
+    """A field annotation has an unsupported format."""
+
+
+class DefaultValueError(ObservableFieldError):
+    """A field default cannot be constructed."""
+
+
+class AccessViolationError(ObservableFieldError):
+    """A field operation violates its access policy."""
+
+
+class ReadAccessViolationError(AccessViolationError):
+    """Reading the field is forbidden."""
+
+
+class WriteAccessViolationError(AccessViolationError):
+    """Writing the field is forbidden."""
+
+
+class PropertyDefinitionError(ObservableFieldError):
+    """An observable property has an invalid definition."""
+
+
+class GetterDefinitionError(ObservableFieldError):
+    """An observable getter has an invalid definition."""
+
+
+class SetterDefinitionError(ObservableFieldError):
+    """An observable setter has an invalid definition."""
+
+
+class Access(IntFlag):
+    """Access policy of an observable field.
+
+    Attributes:
+        none (int): No access. The field cannot be written or read. This can be
+          useful to have a notification only field. All fields can be observed.
+        read (int): Read access. Allows the field to be read.
+        write (int): Write access. Allows the field to be written.
+    """
+
+    # Lowercase flag names are part of the public Access.read / Access.write API.
+    # pylint: disable=invalid-name
+    none = 0
+    read = e_auto()
+    write = e_auto()
+    both = read | write
+    r = read
+    w = write
+    rw = read | write
+
+
+class Empty:
+    """Represent a value not provided."""
+
+    def __new__(cls) -> type[Empty]:
+        return Empty
+
+    def __repr__(self) -> str:
+        return "Observably Empty"
+
+    def __bool__(self) -> bool:
+        return False
+
+
+class Auto:
+    """Request the default to be automatically derived from the field's type annotation."""
+
+    def __new__(cls) -> type[Auto]:
+        return Auto
+
+    def __repr__(self) -> str:
+        return "Observably Auto"
+
+
+class ObservableFieldDecorators[T, I]:
+    """Collect callbacks declared with field decorators."""
+
+    convert: Callable[[I], T] | None = None
+    compare: Callable[[T, T], bool] | None = None
+    assign: Callable[[Observable, T], None] | None = None
+    set: Callable[[Observable, I], None] | None = None
+    get: Callable[[Observable], T] | None = None
+
+    def converter(self, converter: Callable[[I], T]) -> Callable[[I], T]:
+        """Register a conversion callback and return it unchanged."""
+        self.convert = converter
+        return converter
+
+    def comparator(self, comparator: Callable[[T, T], bool]) -> Callable[[T, T], bool]:
+        """Register the comparison used to suppress unchanged-value notifications."""
+        self.compare = comparator
+        return comparator
+
+    def assigner[S: Observable](
+        self, assigner: Callable[[S, T], None]
+    ) -> Callable[[S, T], None]:
+        """Register the callback that stores a converted value."""
+        self.assign = cast(Callable[[Observable, T], None], assigner)
+        return assigner
+
+    def setter[S: Observable](
+        self, setter: Callable[[S, I], None]
+    ) -> Callable[[S, I], None]:
+        """Register a callback that replaces the default setter."""
+        self.set = cast(Callable[[Observable, I], None], setter)
+        return setter
+
+    def getter[S: Observable](self, getter: Callable[[S], T]) -> Callable[[S], T]:
+        """Register a callback that replaces the default getter."""
+        self.get = cast(Callable[[Observable], T], getter)
+        return getter
+
+
+@dataclass
+class AutoField[T, I = T](ObservableFieldDecorators[T, I]):
+    """Field configuration whose types are supplied by the class annotation."""
+
+    # The configuration exposes each independent descriptor option explicitly.
+    # pylint: disable=too-many-instance-attributes
+    default: T | type[Empty] | type[Auto] = Empty
+    default_factory: Callable[[], T] | None = None
+    access: Access = Access.both
+    custom_annotation_registry: AnnotationsRegistry | None = None
+    force_type: tuple[Any, Any] | type[Empty] = Empty
+    convert: Callable[[I], T] | None = None
+    compare: Callable[[T, T], bool] | None = None
+    assign: Callable[[Observable, T], None] | None = None
+    set: Callable[[Observable, I], None] | None = None
+    get: Callable[[Observable], T] | None = None
+
+    def as_observable_field(self) -> ObservableField[T, I]:
+        """Build a descriptor with this configuration and its callbacks."""
+        return ObservableField[T, I](
+            default=self.default,
+            default_factory=self.default_factory,
+            access=self.access,
+            custom_annotation_registry=self.custom_annotation_registry,
+            force_type=self.force_type,
+            converter=self.convert,
+            comparator=self.compare,
+            assigner=self.assign,
+            setter=self.set,
+            getter=self.get,
+        )
+
+
+# Keep the existing positional API for the independent descriptor options.
+# pylint: disable-next=too-many-arguments,too-many-positional-arguments
+def auto_field[T, I = T](
+    default: T | type[Empty] | type[Auto] = Empty,
+    default_factory: Callable[[], T] | None = None,
+    access: Access = Access.both,
+    custom_annotation_registry: AnnotationsRegistry | None = None,
+    force_type: tuple[Any, Any] | type[Empty] = Empty,
+    converter: Callable[[I], T] | None = None,
+    comparator: Callable[[T, T], bool] | None = None,
+    assigner: Callable[[Observable, T], None] | None = None,
+    setter: Callable[[Observable, I], None] | None = None,
+    getter: Callable[[Observable], T] | None = None,
+) -> ObservableField[T, I]:
+    """Declare a field; the metaclass replaces this configuration with a descriptor.
+
+    The return type permits assignment to an ObservableField annotation while the
+    runtime configuration retains the decorator methods used in the class body.
+    """
+    configuration = AutoField[T, I](
+        default,
+        default_factory,
+        access,
+        custom_annotation_registry,
+        force_type,
+        converter,
+        comparator,
+        assigner,
+        setter,
+        getter,
+    )
+    # The metaclass turns this declaration into a descriptor before the class is used.
+    return cast(ObservableField[T, I], configuration)
+
+
+class ObservableField[T, I = T](ObservableFieldDecorators[T, I]):
+    """Descriptor that converts values, controls access, and notifies observers."""
+
+    # Each callback and resolved field option is stored independently.
+    # pylint: disable=too-many-instance-attributes
+    # Keep the existing constructor's positional API.
+    # pylint: disable-next=too-many-arguments,too-many-positional-arguments
+    def __init__(
+        self,
+        default: T | type[Empty] | type[Auto] = Empty,
+        default_factory: Callable[[], T] | None = None,
+        access: Access = Access.both,
+        custom_annotation_registry: AnnotationsRegistry | None = None,
+        force_type: tuple[Any, Any] | type[Empty] = Empty,
+        converter: Callable[[I], T] | None = None,
+        comparator: Callable[[T, T], bool] | None = None,
+        assigner: Callable[[Observable, T], None] | None = None,
+        setter: Callable[[Observable, I], None] | None = None,
+        getter: Callable[[Observable], T] | None = None,
+    ) -> None:
+
+        if default is not Empty and default_factory is not None:
+            raise ValueError(
+                "default_value and default_factory can not be provided at the same time."
+            )
+
+        self.__post_value = (
+            default,
+            force_type,
+            converter,
+            comparator,
+            assigner,
+            setter,
+            getter,
+        )
+
+        self.default_factory = default_factory
+        self._registry = custom_annotation_registry or annotation_registry()
+        self.access = access
+
+        self.name = "Undefined"
+
+    def __post_init__(self) -> None:
+        default_value, force_type, converter, comparator, assigner, setter, getter = (
+            self.__post_value
+        )
+        del self.__post_value
+        if isinstance(force_type, tuple):
+            _type, input_types = force_type
+        elif (orig_class := getattr(self, "__orig_class__", None)) is not None:
+            _type, input_types = get_args(orig_class)
+            if isinstance(input_types, TypeVar):
+                input_types = _type
+        else:
+            raise ValueError(
+                "ObservableField must be used with an Observable class. If you think it is done "
+                "properly but still fails, please open an issue on github. To bypass this error, "
+                "you can provide "
+                "the type and input types manually through force_type."
+            )
+        self.default = self.__make_default(default_value, self.default_factory, _type)
+        self.type = _type
+        self.input_types = input_types
+
+        self.default_convert: Callable[[I], T] = (
+            self._registry.converter_from_annotation(_type)
+        )
+        self._converter: Callable[[I], T] = converter or self.default_convert
+        self._comparator: Callable[[Any, Any], bool] = (
+            comparator or self.default_compare
+        )
+        self._assigner: Callable[[Observable, T], None] = (
+            assigner or self.default_assign
+        )
+        self._setter: Callable[[Observable, I], None] = setter or self.default_set
+        self._getter: Callable[[Observable], T] = getter or self.default_get
+
+    def __make_default(
+        self,
+        default: T | type[Empty] | type[Auto],
+        factory: Callable[[], T] | None,
+        annotation: Any,
+    ) -> T | type[Empty]:
+        if default is Auto:
+            return self._registry.default_annotation(annotation)
+        if default is not Empty:
+            return cast(T, default)
+        if factory is not None:
+            return factory()
+        return Empty
+
+    def default_compare(self, value1: Any, value2: Any) -> bool:
+        """Compare scalar or NumPy values for equality."""
+        if isinstance(value1, np.ndarray) or isinstance(value2, np.ndarray):
+            return np.array_equal(value1, value2)
+        return value1 == value2
+
+    def default_assign(self, instance: Observable, value: T) -> None:
+        """Store a converted value in the owning instance."""
+        # The descriptor and its owner share the module's internal storage protocol.
+        # pylint: disable=protected-access
+        instance._observable_values[self] = value
+
+    def default_set(self, instance: Observable, value: I) -> None:
+        """Convert and store an input, notifying observers when its value changes."""
+        # pylint: disable=protected-access
+        new_value = self._converter(value)
+        if self in instance._observable_values and self._comparator(
+            instance._observable_values[self], new_value
+        ):
+            return
+        self._assigner(instance, new_value)
+        instance.notify(self, value)
+
+    def default_get(self, instance: Observable) -> T:
+        """Return the stored value or default, enforcing the read policy."""
+        # pylint: disable=protected-access
+        if Access.read not in self.access:
+            raise ReadAccessViolationError(
+                f"Cannot read attribute '{self.name}', read is not allowed."
+            )
+        if Access.write not in self.access:
+            if self.default is not Empty:
+                return cast(T, self.default)
+            raise UninitializedError(
+                f"Attribute '{self.name}' has not value and is not writable."
+            )
+        if self in instance._observable_values:
+            return instance._observable_values[self]
+        if self.default is not Empty:
+            return cast(T, self.default)
+        raise UninitializedError(f"Attribute '{self.name}' is not initialized.")
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        self.name = name
+
+    @overload
+    def __get__(
+        self, instance: None, owner: type[Observable] | None = None
+    ) -> Self: ...
+
+    @overload
+    def __get__(
+        self, instance: Observable, owner: type[Observable] | None = None
+    ) -> T: ...
+
+    def __get__(
+        self, instance: Observable | None, owner: type[Observable] | None = None
+    ) -> T | Self:
+        if instance is None:
+            return self
+        return self._getter(instance)
+
+    def __set__(self, instance: Observable, value: I) -> None:
+        if Access.write not in self.access:
+            raise WriteAccessViolationError(
+                f"Cannot write attribute '{self.name}', write is not allowed."
+            )
+        self._setter(instance, value)
+
+
+class ObservableMeta(type):
+    """Resolve field declarations and collect inherited descriptors."""
+
+    def __new__(
+        mcs,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, Any],
+        /,
+        **kwargs: Any,
+    ) -> ObservableMeta:
+        # Python 3.14 defers class annotations unless postponed annotations are enabled.
+        if sys.version_info >= (3, 14):
+            # Import only on interpreters that provide annotationlib.
+            # pylint: disable-next=import-outside-toplevel
+            from annotationlib import (
+                Format,
+                call_annotate_function,
+                get_annotate_from_class_namespace,
+            )
+
+            if "__annotations__" not in namespace:
+                annotate = get_annotate_from_class_namespace(namespace)
+                if annotate is not None:
+                    namespace["__annotations__"] = call_annotate_function(
+                        annotate, Format.FORWARDREF
+                    )
+
+        fields = mcs._collect_observable_fields(bases, namespace)
+        # Inherited descriptors have already been finalized by their declaring class.
+        for value in namespace.values():
+            if isinstance(value, ObservableField):
+                value.__post_init__()
+        mcs._populate_observables(namespace, fields)
+        return super().__new__(mcs, name, bases, namespace, **kwargs)
+
+    @classmethod
+    def _collect_observable_fields(
+        mcs, bases: tuple[type, ...], namespace: dict[str, Any]
+    ) -> dict[str, ObservableField[Any, Any]]:
+        # The metaclass collects the same private field map that it creates below.
+        # pylint: disable=protected-access
+        fields: dict[str, ObservableField[Any, Any]] = {}
+        for base in bases:
+            if hasattr(base, "_observable_fields"):
+                fields.update(base._observable_fields)
+        for name, value in namespace.items():
+            if isinstance(value, ObservableField):
+                fields[name] = value
+            if isinstance(value, AutoField):
+                fields[name] = mcs._process_auto_field(namespace, name, value)
+                namespace[name] = fields[name]
+        return fields
+
+    @classmethod
+    def _process_auto_field(
+        mcs, namespace: dict[str, Any], name: str, field: AutoField[Any, Any]
+    ) -> ObservableField[Any, Any]:
+        annotation = namespace.get("__annotations__", {}).get(name, None)
+        if annotation is None:
+            raise TypeError(f"Automatic field '{name}' must have a type annotation.")
+        module = sys.modules.get(namespace.get("__module__", ""))
+        nglobals = module.__dict__ if module is not None else None
+        annotation = resolve_annotation_types({name: annotation}, nglobals, namespace)[
+            name
+        ]
+        orig = get_origin(annotation)
+        if orig is None or orig is not ObservableField:
+            raise TypeError(
+                f"Automatic field '{name}' must be annotated as an ObservableField."
+            )
+        of = field.as_observable_field()
+        setattr(of, "__orig_class__", annotation)
+        return of
+
+    @classmethod
+    def _populate_observables(
+        mcs,
+        namespace: dict[str, Any],
+        fields: dict[str, ObservableField[Any, Any]],
+    ) -> None:
+        namespace["_observable_fields"] = fields
+
+
+class Observable(metaclass=ObservableMeta):
+    """Owner of observable values and per-instance observer subscriptions."""
+
+    _observable_fields: dict[str, ObservableField[Any, Any]]
+    _observable_values: dict[ObservableField[Any, Any], Any]
+    _observers_internal: dict[ObservableField[Any, Any], list[Observer]]
+    _observers: dict[ObservableField[Any, Any], list[Observer]]
+
+    def __new__(cls, *_args: Any, **_kwargs: Any) -> Self:
+        # Initialize before subclass __init__, which may immediately assign fields
+        # without calling super().__init__. Only field descriptors are shared.
+        instance = super().__new__(cls)
+        instance._observable_values = {}
+        instance._observers_internal = {f: [] for f in cls._observable_fields.values()}
+        instance._observers = {f: [] for f in cls._observable_fields.values()}
+        return instance
+
+    @property
+    def F(self) -> type[Self]:  # pylint: disable=invalid-name
+        """Convenience property to access the ObservableField types.
+        For example in a method of the class MyClass(Observable), instead of
+        `self.register_observer(MyClass.my_field, lambda x: print(x))`
+        you can write `self.register_observer(self.F.my_field, lambda x: print(x))`.
+        """
+        return type(self)
+
+    def set_val[T, I](self, of: ObservableField[T, I], val: I) -> None:
+        """Write through a descriptor supplied explicitly by the caller."""
+        # Descriptor dispatch is intentional; there is no equivalent set() method.
+        of.__set__(self, val)  # pylint: disable=unnecessary-dunder-call
+
+    def get_val[T, I](self, of: ObservableField[T, I]) -> T:
+        """Read through a descriptor supplied explicitly by the caller."""
+        return of.__get__(self)  # pylint: disable=unnecessary-dunder-call
+
+    def _register_observer_internal(
+        self, of: ObservableField[Any, Any], observer: Observer
+    ) -> Observer:
+        self._observers_internal[of].append(observer)
+        return observer
+
+    def _remove_observer_internal(
+        self, of: ObservableField[Any, Any], observer: Observer
+    ) -> None:
+        self._observers_internal[of].remove(observer)
+
+    def get_observers_internal(self, of: ObservableField[Any, Any]) -> list[Observer]:
+        """Return a copy of the field's internal subscription list."""
+        return copy(self._observers_internal[of])
+
+    def register_observer(
+        self, of: ObservableField[Any, Any], observer: Observer
+    ) -> Observer:
+        """Subscribe a callback to this instance's field and return the callback."""
+        self._observers[of].append(observer)
+        return observer
+
+    def remove_observer(
+        self, of: ObservableField[Any, Any], observer: Observer
+    ) -> None:
+        """Remove a previously registered callback from this instance's field."""
+        self._observers[of].remove(observer)
+
+    def get_observers(self, of: ObservableField[Any, Any]) -> list[Observer]:
+        """Return a copy of the field's public subscription list."""
+        return copy(self._observers[of])
+
+    def notify(
+        self,
+        of_s: ObservableField[Any, Any] | list[ObservableField[Any, Any]],
+        *a: Any,
+        **kw: Any,
+    ) -> None:
+        """Notify internal and public subscribers of one or more fields."""
+        if isinstance(of_s, ObservableField):
+            of_s = [of_s]
+        for of in of_s:
+            for observer in self._observers_internal[of]:
+                observer(*a, **kw)
+            for observer in self._observers[of]:
+                observer(*a, **kw)

sg_observable-0.1.0a0/src/sg_observable.egg-info/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: sg-observable
+Version: 0.1.0a0
+Summary: Typed observable fields with conversion and change notifications
+License: MIT
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sg-metacore>=0.1.0a1
+Requires-Dist: numpy
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pyright>=1.1.411; extra == "dev"
+Dynamic: license-file
+
+# observable
+
+Observable fields with conversion, access policies, and change notifications.
+Requires Python 3.13 or newer.
+
+## Installation
+
+Install the `sg-observable` package from PyPI:
+
+```bash
+python -m pip install sg-observable
+```
+
+Pip also installs its dependencies: `sg-metacore` from PyPI and NumPy.
+
+## Usage
+
+```python
+from observable.observable import Observable, ObservableField, auto_field
+
+class Counter(Observable):
+    value: ObservableField[int, str] = auto_field(default=0)
+
+counter = Counter()
+counter.value = "42"       # Writes accept str and convert to int.
+assert counter.value == 42 # Reads return int.
+```
+
+## Runtime and typing
+
+`src/observable/observable.py` contains the implementation and its public type
+annotations, including descriptor overloads and the types of field decorators.
+
+`auto_field()` is intended for annotated declarations in an `Observable` class.
+At runtime it returns an `AutoField` configuration that the metaclass replaces
+with an `ObservableField`. Its return annotation describes that resulting
+descriptor, with a localized cast in the factory to account for the metaclass
+transformation and preserve the field's read and write types.
+Use `AutoField` directly when working with a configuration outside a class body.
+
+The wheel includes a `py.typed` marker so type checkers use the annotations in
+the implementation. Existing comments and TODOs remain in the implementation.
+
+## Development
+
+From the `observable` project directory, install the development dependencies
+and run the checks. MetaCore is installed as the `sg-metacore` PyPI dependency.
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pyright --project pyproject.toml
+python -m pytest
+```
+
+The tests cover runtime behavior and rejected type errors.
+Static examples under `tests/typing/` verify descriptor inference and
+callback signatures.

sg_observable-0.1.0a0/src/sg_observable.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+MANIFEST.in
+pyproject.toml
+readme.md
+src/observable/__init__.py
+src/observable/observable.py
+src/observable/py.typed
+src/sg_observable.egg-info/PKG-INFO
+src/sg_observable.egg-info/SOURCES.txt
+src/sg_observable.egg-info/dependency_links.txt
+src/sg_observable.egg-info/requires.txt
+src/sg_observable.egg-info/top_level.txt
+tests/test_observable.py
+tests/test_observable_annotations.py
+tests/test_observable_typing.py
+tests/typing/invalid.py.txt
+tests/typing/valid.py

sg_observable-0.1.0a0/src/sg_observable.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sg_observable-0.1.0a0/src/sg_observable.egg-info/requires.txt

@@ -0,0 +1,6 @@
+sg-metacore>=0.1.0a1
+numpy
+
+[dev]
+pytest>=7.0
+pyright>=1.1.411

sg_observable-0.1.0a0/src/sg_observable.egg-info/top_level.txt

@@ -0,0 +1 @@
+observable

sg_observable-0.1.0a0/tests/test_observable.py

@@ -0,0 +1,143 @@
+"""Regression coverage for typed descriptors and observable instance behavior."""
+
+from __future__ import annotations
+
+from typing import assert_type
+from pathlib import Path
+
+import pytest
+
+from metacore.annotations import AnnotationsRegistry
+from observable.observable import (
+    Access,
+    Auto,
+    Observable,
+    ObservableField,
+    ReadAccessViolationError,
+    UninitializedError,
+    WriteAccessViolationError,
+    auto_field,
+)
+
+
+class Counter(Observable):
+    value: ObservableField[int, str] = auto_field(default=0)
+
+
+def test_field_annotations_resolve_module_and_class_local_names():
+    class Scoped(Observable):
+        from decimal import Decimal as Scalar
+
+        value: ObservableField[Scalar, str] = auto_field(default=Auto)
+        directory: ObservableField[Path, str] = auto_field(default=Auto)
+
+    instance = Scoped()
+    instance.value = "1.25"
+    instance.directory = "documents"
+    assert instance.value == Scoped.Scalar("1.25")
+    assert instance.directory == Path("documents")
+
+
+def test_conversion_notifications_and_instance_isolation():
+    first, second = Counter(), Counter()
+    events: list[str] = []
+    first.register_observer(Counter.value, events.append)
+
+    first.value = "42"
+    first.value = "42"
+
+    assert first.value == 42
+    assert second.value == 0
+    assert events == ["42"]
+    assert second.get_observers(Counter.value) == []
+
+
+def test_explicit_descriptor_access_preserves_types():
+    counter = Counter()
+    counter.set_val(Counter.value, "3")
+    assert counter.get_val(Counter.value) == 3
+    assert_type(counter.get_val(Counter.value), int)
+    assert_type(Counter.value, ObservableField[int, str])
+
+
+def test_inherited_fields_are_not_initialized_twice():
+    class Child(Counter):
+        other: ObservableField[int, str] = auto_field(default=1)
+
+    first, second = Child(), Child()
+    first.value = "7"
+    first.other = "8"
+    assert first.value == 7
+    assert first.other == 8
+    assert second.value == 0
+    assert second.other == 1
+
+
+def test_subclass_can_assign_fields_in_its_initializer():
+    class Initialized(Counter):
+        def __init__(self, value: str):
+            self.value = value
+
+    assert Initialized("5").value == 5
+
+
+def test_converter_decorator():
+    class Decorated(Observable):
+        value: ObservableField[int, str] = auto_field(default=0)
+
+        @staticmethod
+        @value.converter
+        def parse(value: str) -> int:
+            return int(value) + 10
+
+    instance = Decorated()
+    instance.value = "2"
+    assert instance.value == 12
+
+
+def test_custom_registry_and_automatic_default():
+    registry = AnnotationsRegistry()
+    registry.register_converter(int, lambda value: int(value) + 10)
+
+    class Custom(Observable):
+        values = ObservableField[list[int], list[str]](
+            default=Auto, custom_annotation_registry=registry
+        )
+
+    instance = Custom()
+    assert instance.values == []
+    instance.values = ["1", "2"]
+    assert instance.values == [11, 12]
+
+
+def test_read_and_write_access_policies():
+    class Restricted(Observable):
+        read_only = ObservableField[int](default=1, access=Access.read)
+        write_only = ObservableField[int](access=Access.write)
+
+    instance = Restricted()
+    assert instance.read_only == 1
+    with pytest.raises(WriteAccessViolationError):
+        instance.read_only = 2
+    instance.write_only = 3
+    with pytest.raises(ReadAccessViolationError):
+        _ = instance.write_only
+
+
+def test_uninitialized_field():
+    class Pending(Observable):
+        value = ObservableField[int]()
+
+    with pytest.raises(UninitializedError):
+        _ = Pending().value
+
+
+def test_observer_removal_and_copied_subscriptions():
+    counter = Counter()
+    events: list[str] = []
+    observer = counter.register_observer(Counter.value, events.append)
+    counter.get_observers(Counter.value).clear()
+    counter.value = "1"
+    counter.remove_observer(Counter.value, observer)
+    counter.value = "2"
+    assert events == ["1"]

sg_observable-0.1.0a0/tests/test_observable_annotations.py

@@ -0,0 +1,46 @@
+"""Exercise default annotation behavior without the future annotations import."""
+
+from decimal import Decimal
+from pathlib import Path
+
+import pytest
+
+from observable.observable import Auto, Observable, ObservableField, auto_field
+
+
+def test_default_annotations_resolve_global_and_class_local_types():
+    class Model(Observable):
+        Scalar = Decimal
+        value: ObservableField[Scalar, str] = auto_field(default=Auto)
+        directory: ObservableField[Path, str] = auto_field(default=Auto)
+
+    instance = Model()
+    assert instance.value == Decimal(0)
+    events = []
+    instance.register_observer(Model.value, events.append)
+    instance.value = "1.25"
+    instance.directory = "documents"
+    assert instance.value == Decimal("1.25")
+    assert instance.directory == Path("documents")
+    assert events == ["1.25"]
+
+
+def test_default_annotations_support_quoted_fields_and_inheritance():
+    class Parent(Observable):
+        value: "ObservableField[int, str]" = auto_field(default=0)
+
+    class Child(Parent):
+        other: ObservableField[int, str] = auto_field(default=1)
+
+    first, second = Child(), Child()
+    first.value = "2"
+    first.other = "3"
+    assert (first.value, first.other) == (2, 3)
+    assert (second.value, second.other) == (0, 1)
+
+
+def test_missing_annotations_still_fail_with_a_clear_error():
+    with pytest.raises(TypeError, match="must have a type annotation"):
+
+        class Missing(Observable):
+            value = auto_field(default=0)

sg_observable-0.1.0a0/tests/test_observable_typing.py

@@ -0,0 +1,60 @@
+"""Ensure incorrect consumer code is rejected by the inline annotations."""
+
+import json
+from pathlib import Path
+import subprocess
+import sys
+
+import metacore
+from observable import observable as implementation
+
+
+def test_typing_rejects_incorrect_defaults_writes_reads_and_callbacks(tmp_path):
+    text = (Path(__file__).parent / "typing/invalid.py.txt").read_text(encoding="utf-8")
+    sample = tmp_path / "invalid.py"
+    sample.write_text(text, encoding="utf-8")
+    config = tmp_path / "pyrightconfig.json"
+    config.write_text(
+        json.dumps(
+            {
+                "typeCheckingMode": "standard",
+                "pythonVersion": "3.13",
+                "extraPaths": [
+                    str(Path(implementation.__file__).resolve().parents[1]),
+                    str(Path(metacore.__file__).resolve().parents[1]),
+                ],
+            }
+        ),
+        encoding="utf-8",
+    )
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "pyright",
+            "--project",
+            str(config),
+            "--pythonpath",
+            sys.executable,
+            "--outputjson",
+            str(sample),
+        ],
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+    diagnostics = json.loads(result.stdout)
+    errors = [
+        item
+        for item in diagnostics["generalDiagnostics"]
+        if item["severity"] == "error"
+    ]
+    expected_lines = {
+        index
+        for index, line in enumerate(text.splitlines())
+        if "# expected-error" in line
+    }
+    assert result.returncode == 1, result.stdout + result.stderr
+    assert {item["range"]["start"]["line"] for item in errors} == expected_lines, errors
+    assert len(errors) == len(expected_lines), errors
+    assert diagnostics["summary"]["warningCount"] == 0, diagnostics

sg_observable-0.1.0a0/tests/typing/invalid.py.txt

@@ -0,0 +1,19 @@
+from observable.observable import Observable, ObservableField, auto_field
+
+
+class Model(Observable):
+    value: ObservableField[int, str] = auto_field(default=0)
+    bad_default: ObservableField[int, str] = auto_field(default="wrong")  # expected-error
+
+
+model = Model()
+model.value = 42  # expected-error
+wrong_read: str = model.value  # expected-error
+model.set_val(Model.value, 42)  # expected-error
+
+
+def wrong_converter(value: str) -> str:
+    return value
+
+
+Model.value.converter(wrong_converter)  # expected-error

sg_observable-0.1.0a0/tests/typing/valid.py

@@ -0,0 +1,43 @@
+"""Examples checked against the inline type annotations; not executed as tests."""
+
+from typing import Callable, assert_type
+
+from observable.observable import (
+    Auto,
+    AutoField,
+    Observable,
+    ObservableField,
+    auto_field,
+)
+
+
+class Model(Observable):
+    value: ObservableField[int, str] = auto_field(default=0)
+    automatic: ObservableField[int, str] = auto_field(default=Auto)
+    numbers: ObservableField[list[int], list[str]] = auto_field(default_factory=list)
+
+    @staticmethod
+    @value.converter
+    def parse(value: str) -> int:
+        return int(value)
+
+
+def check_types(model: Model) -> None:
+    assert_type(Model.value, ObservableField[int, str])
+    assert_type(model.value, int)
+    assert_type(model.automatic, int)
+    assert_type(model.numbers, list[int])
+    assert_type(model.get_val(Model.value), int)
+    assert_type(model.F, type[Model])
+    model.value = "42"
+    model.numbers = ["1", "2"]
+    model.set_val(Model.value, "3")
+
+    def accept_converter(converter: Callable[[str], int]) -> None:
+        _ = converter
+
+    accept_converter(Model.value.converter(int))
+    config = AutoField[int, str](default=0)
+    assert_type(config.as_observable_field(), ObservableField[int, str])
+    field: ObservableField[int, str] = auto_field(default=0)
+    assert_type(field, ObservableField[int, str])