cooptools 1.77__tar.gz → 1.78__tar.gz

{cooptools-1.77 → cooptools-1.78}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cooptools
-Version: 1.77
+Version: 1.78
 Summary: Generic Tooling
 Home-page: https://github.com/tylertjburns/cooptools
 Author: tburns

cooptools-1.78/cooptools/expertise/__init__.py

@@ -0,0 +1,6 @@
+from cooptools.expertise.expertiseArgs import *
+from cooptools.expertise.expertiseSchedules import *
+from cooptools.expertise.expertise_state import (
+    expertise_from_state,
+    expertise_to_state,
+)

cooptools-1.78/cooptools/expertise/expertise_state.py

@@ -0,0 +1,58 @@
+"""Expertise across the JSON boundary.
+
+Beside the calculator it serializes rather than in a persistence package, because
+what these two functions know about is *expertise* -- which accumulator holds the
+truth and which views are derived -- and only incidentally that the destination is
+JSON. Grouped by mechanism they would sit next to enum conversion, which they have
+nothing in common with; grouped by subject they sit next to the thing that breaks
+them when it changes.
+
+Functions over `ExpertiseCalculator` rather than methods on it, so that reading
+and writing its state is available without widening the calculator's own API.
+
+Deliberately asymmetric, and worth knowing why:
+
+- Reading has to reach `_expertise_args`, because the calculator exposes only
+  derived views (`PercExpert`, `CurrentTimeReductionPerc`) and neither can be
+  inverted back into the accumulator that produced it.
+- Writing does not, because `schedule` is public and the increments are public,
+  so a fresh calculator can be built and wound forward. That is also what makes
+  applying twice give the same answer as applying once -- incrementing an
+  existing calculator would accumulate instead of replace.
+
+The read is the half that would break if the calculator's internals moved, which
+is the argument for these eventually becoming methods on it.
+"""
+import logging
+from typing import Any, Dict
+
+from cooptools.expertise.expertiseSchedules import ExpertiseCalculator
+
+logger = logging.getLogger(__name__)
+
+
+def expertise_to_state(calculator: ExpertiseCalculator) -> Dict[str, Any]:
+    """The accumulators behind an expertise calculator.
+
+    The schedule is not written -- it is definition, rebuilt from tuning by
+    whatever constructs the calculator's owner.
+    """
+    args = calculator._expertise_args
+    return {'n_runs': args.n_runs,
+            'accumulated_s': args.accumulated_s,
+            'exp': args.exp}
+
+
+def expertise_from_state(state: Dict[str, Any],
+                         calculator: ExpertiseCalculator) -> ExpertiseCalculator:
+    """A calculator on `calculator`'s schedule, wound to the saved accumulators.
+
+    Returns a new instance rather than mutating: the caller reassigns, which is
+    what makes this replace rather than accumulate.
+    """
+    restored = ExpertiseCalculator(schedule=calculator.schedule)
+    saved = state or {}
+    restored.increment_n_runs(saved.get('n_runs', 0))
+    restored.increment_s_producting(saved.get('accumulated_s', 0))
+    restored.increment_exp(saved.get('exp', 0))
+    return restored

cooptools-1.78/cooptools/persistence/__init__.py

@@ -0,0 +1,36 @@
+"""Handing an object's state out and taking it back, without a base class.
+
+`Stateful` is a structural `typing.Protocol`, so a class conforms by having
+`to_state`/`apply_state` and importing nothing to do it. That is what lets a type
+in one package be persisted by another with no dependency edge pointing back --
+and it is why this belongs in a shared library rather than in whichever consumer
+happened to need it first.
+
+Alongside it is the conversion every state dict of any size ends up needing:
+enums as dict keys, because JSON keys must be strings.
+
+Conversions for a *particular* type live with that type instead --
+`cooptools.expertise.expertise_state` is the worked example. What those functions
+know is which of an expertise calculator's fields holds the truth and which are
+derived; that they happen to end up as JSON is incidental, and grouping them here
+would put them beside enum conversion, which they have nothing in common with.
+
+What is deliberately *not* here: anything about where state is written. A file
+format, a directory of saves, a version envelope around a whole document -- those
+are decisions about an application, not about an object handing over its state.
+"""
+from cooptools.persistence.stateful import (
+    StateDict,
+    StateError,
+    StateVersionError,
+    Stateful,
+    VERSION_KEY,
+    check_version,
+    version_of,
+)
+from cooptools.persistence.enum_state import (
+    enum_from_state,
+    enum_keyed_from_state,
+    enum_keyed_to_state,
+    enum_to_state,
+)

cooptools-1.78/cooptools/persistence/enum_state.py

@@ -0,0 +1,81 @@
+"""Enums across the JSON boundary.
+
+Most state blocks of any size carry at least one enum-keyed
+quantity map -- what a stockpile holds, what a villager carries, what a recipe
+costs -- and JSON has no enum and no non-string key. Left to each call site, that
+translation gets written seven ways: by `.value` in one place and `.name` in
+another, crashing on an unknown member here and silently dropping it there.
+
+**Names, not values.** A member's `name` is the thing the rest of the codebase
+already treats as its stable identity (log lines, config keys, file keys). Its
+`value` is frequently `auto()`, which renumbers the moment somebody inserts a
+member -- so a file written by value would read back as a *different* resource
+after an unrelated edit, with nothing to report it.
+"""
+import logging
+from enum import Enum
+from typing import Dict, Mapping, Optional, Type, TypeVar
+
+logger = logging.getLogger(__name__)
+
+E = TypeVar('E', bound=Enum)
+
+
+def enum_to_state(value: Optional[Enum]) -> Optional[str]:
+    """One enum member as its name, passing None through."""
+    return value.name if value is not None else None
+
+
+def enum_from_state(name: Optional[str], enum_cls: Type[E], *,
+                    owner: str = None) -> Optional[E]:
+    """One enum member back from its name.
+
+    An unknown name yields None with a warning rather than raising. A member
+    removed from the code between the write and the read is a real, expected event
+    during development, and it should cost the field rather than the file --
+    every caller already handles None for these (a region with no building, a
+    site with no target tier).
+    """
+    if name is None:
+        return None
+    try:
+        return enum_cls[name]
+    except KeyError:
+        logger.warning(f"{owner or enum_cls.__name__}: '{name}' is not a member of "
+                       f"{enum_cls.__name__} any more -- dropped")
+        return None
+
+
+def enum_keyed_to_state(quantities: Optional[Mapping[Enum, float]]) -> Dict[str, float]:
+    """An enum-keyed quantity map as a name-keyed one.
+
+    Written in the enum's own declaration order rather than the mapping's, so two
+    writes of the same state are byte-identical -- which is what lets a round-trip
+    test compare dicts, and lets two files diff usefully.
+    """
+    if not quantities:
+        return {}
+    members = sorted(quantities.keys(), key=lambda member: list(type(member)).index(member))
+    return {member.name: quantities[member] for member in members}
+
+
+def enum_keyed_from_state(quantities: Optional[Mapping[str, float]],
+                          enum_cls: Type[E], *,
+                          owner: str = None) -> Dict[E, float]:
+    """A name-keyed quantity map back to an enum-keyed one.
+
+    Unknown names are dropped with a warning, for the reason `enum_from_state`
+    gives -- but here the loss is quantified in the log, since goods vanishing
+    from a stockpile is the kind of thing that otherwise gets noticed as a
+    balance mystery three sessions later.
+    """
+    if not quantities:
+        return {}
+    result: Dict[E, float] = {}
+    for name, qty in quantities.items():
+        try:
+            result[enum_cls[name]] = qty
+        except KeyError:
+            logger.warning(f"{owner or enum_cls.__name__}: dropping {qty:g} of '{name}', "
+                           f"which is not a member of {enum_cls.__name__} any more")
+    return result

cooptools-1.78/cooptools/persistence/stateful.py

@@ -0,0 +1,148 @@
+"""The contract every persistable thing implements: hand out your state, and
+take it back.
+
+Deliberately a `typing.Protocol` rather than a base class, because conformance is
+*structural*: a class satisfies this by having the two methods, without importing
+anything from here. That is what lets a class in one package be persisted by
+another with no dependency edge pointing back -- which is the whole reason this
+is a library type rather than one belonging to whoever is doing the persisting.
+
+## State is not definition
+
+The split this protocol exists to enforce: **state is what use changed;
+definition is what built the object.** A production station is built from its
+recipe -- inputs, outputs, a timer callback, a schedule -- and *holds* the
+contents of its stores and how far its current run has got. Only the second half
+belongs in a state dict. The first half is reconstructed by whatever built the
+object the first time, from the same source it used then.
+
+Getting this line wrong in either direction is expensive. Persisting definition
+means a restored object silently pins yesterday's configuration and stops
+tracking the file it should be reading. Persisting too little means the object
+comes back subtly wrong, usually in a way nothing notices for a while.
+
+## Why `apply_state` mutates instead of `from_state` constructing
+
+Almost nothing worth persisting can be rebuilt from a dict alone. The objects
+that carry interesting state are usually constructed with injected collaborators
+-- providers, callbacks, the graph they read -- none of which survive a round trip
+through JSON. A `from_state` classmethod would force every one of them to grow a
+second construction path whose only caller is the loader.
+
+`apply_state` matches how a restore actually goes instead: the object graph is
+rebuilt the ordinary way, so everything exists with its collaborators already
+wired, and the saved state is then poured into objects that are otherwise ready to
+run.
+
+A leaf that genuinely owns nothing may additionally offer a `from_state`
+classmethod as a convenience. The protocol does not ask for one.
+
+## Versioning
+
+Each block carries its own `STATE_VERSION`, stamped under `VERSION_KEY`, and each
+`apply_state` is responsible for reading older shapes of its own block. Versioning
+per class rather than once for the whole file is what stops a new field on one
+class invalidating every file in existence -- and it keeps a migration next to the
+invariant it is migrating, which is the same reason the state lives on the object
+rather than in a central writer.
+"""
+import logging
+from typing import Any, ClassVar, Dict, Protocol, runtime_checkable
+
+logger = logging.getLogger(__name__)
+
+# A JSON-safe mapping: dicts, lists, strings, numbers, bools and None, and
+# nothing else. Enum keys are written as `.name` (see enum_state.py), and any
+# identity-bearing type -- a uuid, a graph Node -- is written as whatever stable
+# name addresses it, never as the object.
+StateDict = Dict[str, Any]
+
+# Where a block's own version lives. Short because it appears once per block, and
+# a file of any size holds a great many blocks.
+VERSION_KEY = "v"
+
+
+class StateError(ValueError):
+    """A state dict could not be read."""
+
+
+class StateVersionError(StateError):
+    """A state dict is a version this build does not understand."""
+
+
+@runtime_checkable
+class Stateful(Protocol):
+    """Hands out its own state, and takes it back.
+
+    Two things to know about checking conformance against this at runtime:
+
+    - **`isinstance` works and covers all three members**, `STATE_VERSION`
+      included, so a class that has the methods but never declared a version is
+      correctly refused.
+    - **`issubclass` raises `TypeError`** on every Python version, because this
+      protocol has a non-method member. Check an instance, never a class.
+
+    And what `isinstance` does *not* buy: `runtime_checkable` compares member
+    presence, never signatures. It catches a conformer that dropped or renamed a
+    member -- the realistic failure for a class in another package that never
+    imports this -- and says nothing about one that changed an argument.
+    """
+
+    STATE_VERSION: ClassVar[int]
+
+    def to_state(self) -> StateDict:
+        """This object's play-state, as JSON-safe primitives.
+
+        Must include `VERSION_KEY`. Must not include anything reconstructed by
+        whatever builds this object -- see the module docstring on state vs.
+        definition.
+        """
+        ...
+
+    def apply_state(self, state: StateDict) -> None:
+        """Adopts `state`, replacing whatever this object currently holds.
+
+        Called on an object that is fully constructed and wired to its
+        collaborators. Implementations replace rather than merge: applying a state
+        twice must leave the same result as applying it once, and a field absent
+        from `state` takes its documented default rather than whatever happened to
+        be there.
+        """
+        ...
+
+
+def version_of(state: StateDict) -> int:
+    """The version stamped on a state block.
+
+    Raises rather than defaulting: an unstamped block is either corrupt or predates
+    versioning, and both are cases where guessing a version reads the rest of the
+    block under rules it was not written to.
+    """
+    if VERSION_KEY not in state:
+        raise StateVersionError(
+            f"State block carries no '{VERSION_KEY}' -- it is corrupt, or was written "
+            f"before this block was versioned")
+    version = state[VERSION_KEY]
+    if not isinstance(version, int) or isinstance(version, bool):
+        raise StateVersionError(
+            f"State block's '{VERSION_KEY}' is {version!r}, which is not a version number")
+    return version
+
+
+def check_version(state: StateDict, *, owner: str, supported: int) -> int:
+    """Returns the block's version, refusing one this build cannot read.
+
+    `owner` names the class in the error, because a load failure often reaches a
+    user as a single line, and "which part of this file is too new" is the whole of
+    what they can act on.
+
+    A version *below* `supported` is returned rather than refused -- that is the
+    case `apply_state` migrates, and this function has no way to know whether it
+    can.
+    """
+    version = version_of(state)
+    if version > supported:
+        raise StateVersionError(
+            f"{owner} state is version {version}, but this build understands up to "
+            f"{supported} -- it was written by a newer build")
+    return version

{cooptools-1.77 → cooptools-1.78}/cooptools.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cooptools
-Version: 1.77
+Version: 1.78
 Summary: Generic Tooling
 Home-page: https://github.com/tylertjburns/cooptools
 Author: tburns

{cooptools-1.77 → cooptools-1.78}/cooptools.egg-info/SOURCES.txt

@@ -61,6 +61,7 @@ cooptools/dataStore/inMemoryDataStore.py
 cooptools/expertise/__init__.py
 cooptools/expertise/expertiseArgs.py
 cooptools/expertise/expertiseSchedules.py
+cooptools/expertise/expertise_state.py
 cooptools/finance/__init__.py
 cooptools/finance/dicounted_cashflow_analysis.py
 cooptools/finance/fund_projection.py
@@ -114,6 +115,9 @@ cooptools/pathing/waypoint.py
 cooptools/pathing/waypointFollower.py
 cooptools/pathing/demo/__init__.py
 cooptools/pathing/demo/server.py
+cooptools/persistence/__init__.py
+cooptools/persistence/enum_state.py
+cooptools/persistence/stateful.py
 cooptools/physics/__init__.py
 cooptools/physics/kinematic.py
 cooptools/physics/kinematic_utils.py
@@ -160,6 +164,7 @@ tests/test_coopEnum.py
 tests/test_currency.py
 tests/test_curves.py
 tests/test_date_utils.py
+tests/test_expertise_state.py
 tests/test_flow_field.py
 tests/test_flow_field_perf.py
 tests/test_fund_projection.py
@@ -169,6 +174,7 @@ tests/test_kinematic_utils.py
 tests/test_os_manip.py
 tests/test_pandas.py
 tests/test_path_utils.py
+tests/test_persistence.py
 tests/test_printing.py
 tests/test_qualifiers.py
 tests/test_sectors.py

{cooptools-1.77 → cooptools-1.78}/setup.py

@@ -7,7 +7,7 @@ with open('requirements.txt') as f:
     requirements = f.read().splitlines()
 
 setuptools.setup(name='cooptools',
-      version='1.77',
+      version='1.78',
       description='Generic Tooling',
       url='https://github.com/tylertjburns/cooptools',
       author='tburns',

cooptools-1.78/tests/test_expertise_state.py

@@ -0,0 +1,120 @@
+"""Coverage for expertise across the JSON boundary.
+
+The pair was moved here from a consumer with no tests of its own, so these are
+new. What matters about it is not the round trip -- three integers survive a dict,
+which would be surprising if it failed -- but the two properties that make it
+usable as *state*:
+
+  * **What is written is the accumulators, not the schedule.** The schedule is
+    definition, rebuilt from tuning by whatever constructs the calculator's owner.
+    Writing it would pin yesterday's tuning into every file.
+  * **Applying twice gives the same answer as applying once.** The functions are
+    deliberately asymmetric for this: reading reaches the private args because the
+    calculator exposes only derived views that cannot be inverted, while writing
+    builds a *fresh* calculator and winds it forward. Incrementing an existing one
+    would accumulate, and a state applied twice would report double the
+    experience.
+
+Runs with:
+    python -m unittest tests.test_expertise_state
+"""
+import unittest
+
+from cooptools.expertise import expertise_from_state, expertise_to_state
+from cooptools.expertise.expertiseSchedules import (ByRunsExpertiseSchedule,
+                                                    ExpertiseCalculator)
+
+
+def _calculator(runs_until_expert: int = 8,
+                max_time_reduction_perc: float = 0.3) -> ExpertiseCalculator:
+    return ExpertiseCalculator(schedule=ByRunsExpertiseSchedule(
+        runs_until_expert=runs_until_expert,
+        max_time_reduction_perc=max_time_reduction_perc))
+
+
+class ExpertiseStateTests(unittest.TestCase):
+    def test__a_fresh_calculator_writes_zeroes(self):
+        self.assertEqual({'n_runs': 0, 'accumulated_s': 0, 'exp': 0},
+                         expertise_to_state(_calculator()))
+
+    def test__the_accumulators_round_trip(self):
+        source = _calculator()
+        source.increment_n_runs(5)
+        source.increment_s_producting(12.5)
+        source.increment_exp(3)
+
+        restored = expertise_from_state(expertise_to_state(source), _calculator())
+        self.assertEqual(expertise_to_state(source), expertise_to_state(restored))
+
+    def test__the_derived_views_come_back_with_them(self):
+        """The accumulators are what is stored precisely because the views follow
+        from them -- so the views are the check that the right thing was stored."""
+        source = _calculator()
+        source.increment_n_runs(4)
+
+        restored = expertise_from_state(expertise_to_state(source), _calculator())
+        self.assertEqual(source.PercExpert, restored.PercExpert)
+        self.assertEqual(source.CurrentTimeReductionPerc,
+                         restored.CurrentTimeReductionPerc)
+
+    def test__the_schedule_is_not_written(self):
+        """It is definition. Writing it would pin the tuning a file was made
+        under into every later read of that file."""
+        state = expertise_to_state(_calculator(runs_until_expert=8))
+        self.assertEqual({'n_runs', 'accumulated_s', 'exp'}, set(state))
+
+    def test__the_schedule_comes_from_the_target_not_the_state(self):
+        """So retuning reaches an object restored from an older file, rather than
+        the file holding it back."""
+        source = _calculator(runs_until_expert=8)
+        source.increment_n_runs(4)
+
+        retuned = _calculator(runs_until_expert=4)
+        restored = expertise_from_state(expertise_to_state(source), retuned)
+
+        self.assertEqual(retuned.schedule, restored.schedule)
+        # Four runs is half-expert on the old schedule and fully expert on the
+        # new one, from the same stored accumulators.
+        self.assertGreater(restored.PercExpert, source.PercExpert)
+
+    def test__applying_twice_equals_applying_once(self):
+        """The asymmetry exists for this. A version that incremented an existing
+        calculator would report double the experience on a second apply."""
+        source = _calculator()
+        source.increment_n_runs(6)
+        source.increment_s_producting(9.0)
+        state = expertise_to_state(source)
+
+        once = expertise_from_state(state, _calculator())
+        twice = expertise_from_state(state, once)
+        self.assertEqual(expertise_to_state(once), expertise_to_state(twice))
+
+    def test__applying_does_not_disturb_the_target(self):
+        """It returns a new calculator, so the caller reassigns -- which is what
+        makes it replace rather than accumulate."""
+        target = _calculator()
+        target.increment_n_runs(2)
+
+        source = _calculator()
+        source.increment_n_runs(7)
+        expertise_from_state(expertise_to_state(source), target)
+
+        self.assertEqual(2, expertise_to_state(target)['n_runs'])
+
+    def test__an_absent_state_restores_a_fresh_calculator(self):
+        """A file written before this was recorded should leave the object at its
+        documented default rather than failing to load."""
+        for empty in (None, {}):
+            with self.subTest(state=empty):
+                restored = expertise_from_state(empty, _calculator())
+                self.assertEqual({'n_runs': 0, 'accumulated_s': 0, 'exp': 0},
+                                 expertise_to_state(restored))
+
+    def test__a_partial_state_takes_defaults_for_what_is_missing(self):
+        restored = expertise_from_state({'n_runs': 3}, _calculator())
+        self.assertEqual({'n_runs': 3, 'accumulated_s': 0, 'exp': 0},
+                         expertise_to_state(restored))
+
+
+if __name__ == '__main__':
+    unittest.main()