prspace 0.1.0__py3-none-any.whl

prspace/__init__.py

@@ -0,0 +1,6 @@
+"""prspace: probability spaces with the same syntax in Python and R."""
+
+from ._core import Condition, Event, PrSpace, UndefinedProbabilityError
+
+__all__ = ["PrSpace", "Event", "Condition", "UndefinedProbabilityError"]
+__version__ = "0.1.0"

prspace/_core.py

@@ -0,0 +1,195 @@
+"""Core objects: PrSpace, Event, and the Condition you get by comparing an Event."""
+
+from __future__ import annotations
+
+import itertools
+import math
+import numbers
+import sys
+from types import FrameType
+from typing import Any
+
+_ids = itertools.count(1)
+
+# The complement of each comparison, e.g. not (X == 0) is (X != 0).
+_NEGATE = {"==": "!=", "!=": "==", "<": ">=", ">=": "<", ">": "<=", "<=": ">"}
+
+
+class UndefinedProbabilityError(KeyError):
+    """Raised when reading ``Pr[cond]`` that was never assigned (directly or via its complement)."""
+
+    def __init__(self, condition: Condition):
+        super().__init__(condition)
+        self.condition = condition
+
+    def __str__(self) -> str:
+        return (
+            f"Pr[{self.condition}] has not been assigned "
+            f"(nor has its complement Pr[{~self.condition}])"
+        )
+
+
+class Event:
+    """A quantity you can make probability statements about.
+
+    Comparing an Event with a value (``S_B == 0``, ``S_B >= 1``) gives a
+    :class:`Condition`, which is what you index a :class:`PrSpace` with.
+
+    If ``name`` is omitted, it is taken from the variable the Event is bound to
+    the first time it is compared, so ``S_B = Event()`` prints as ``S_B``.
+    """
+
+    def __init__(self, name: str | None = None):
+        if name is not None and not isinstance(name, str):
+            raise TypeError("`name` must be a string")
+        self._id = next(_ids)
+        self.name = name
+
+    @property
+    def label(self) -> str:
+        return self.name if self.name is not None else f"E{self._id}"
+
+    def _compare(self, op: str, value: Any, frame: FrameType | None) -> Condition:
+        if isinstance(value, Event):
+            raise TypeError("comparing two Events is not supported yet")
+        try:
+            hash(value)
+        except TypeError:
+            raise TypeError(
+                f"an Event can only be compared with a single value, not {type(value).__name__}"
+            ) from None
+        if self.name is None and frame is not None:
+            self.name = _infer_name(self, frame)
+        return Condition(self, op, value)
+
+    # Python reflects `0 == S_B` to `S_B == 0` (and `1 <= S_B` to `S_B >= 1`) on its own.
+    def __eq__(self, value: Any) -> Condition:  # type: ignore[override]
+        return self._compare("==", value, sys._getframe(1))
+
+    def __ne__(self, value: Any) -> Condition:  # type: ignore[override]
+        return self._compare("!=", value, sys._getframe(1))
+
+    def __lt__(self, value: Any) -> Condition:
+        return self._compare("<", value, sys._getframe(1))
+
+    def __le__(self, value: Any) -> Condition:
+        return self._compare("<=", value, sys._getframe(1))
+
+    def __gt__(self, value: Any) -> Condition:
+        return self._compare(">", value, sys._getframe(1))
+
+    def __ge__(self, value: Any) -> Condition:
+        return self._compare(">=", value, sys._getframe(1))
+
+    def __hash__(self) -> int:
+        return hash(("prspace.Event", self._id))
+
+    def __repr__(self) -> str:
+        return f"<Event {self.label}>"
+
+
+class Condition:
+    """An event such as ``S_B == 0``. Use it as a key: ``Pr[S_B == 0]``.
+
+    ``~cond`` is the complement (``~(S_B == 0)`` is ``S_B != 0``).
+    """
+
+    __slots__ = ("event", "op", "value")
+
+    def __init__(self, event: Event, op: str, value: Any):
+        self.event = event
+        self.op = op
+        self.value = value
+
+    @property
+    def _key(self) -> tuple:
+        return (self.event._id, self.op, self.value)
+
+    def __invert__(self) -> Condition:
+        return Condition(self.event, _NEGATE[self.op], self.value)
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Condition) and self._key == other._key
+
+    def __hash__(self) -> int:
+        return hash(self._key)
+
+    def __bool__(self) -> bool:
+        raise TypeError(
+            f"`{self}` is an event, not True/False; use it as a key, e.g. Pr[{self}]"
+        )
+
+    def __str__(self) -> str:
+        return f"{self.event.label} {self.op} {self.value!r}"
+
+    def __repr__(self) -> str:
+        return f"<Condition {self}>"
+
+
+class PrSpace:
+    """A probability space: assign ``Pr[cond] = p`` and read back ``Pr[cond]``.
+
+    Complements are derived: after ``Pr[X == 0] = 0.3``, ``Pr[X != 0]`` is 0.7.
+    Assigning a condition replaces any stored value for its complement.
+    """
+
+    def __init__(self) -> None:
+        self._store: dict[tuple, tuple[Condition, float]] = {}
+
+    def __setitem__(self, condition: Condition, p: Any) -> None:
+        condition = _as_condition(condition)
+        p = _as_probability(p, condition)
+        self._store.pop((~condition)._key, None)
+        self._store[condition._key] = (condition, p)
+
+    def __getitem__(self, condition: Condition) -> float:
+        condition = _as_condition(condition)
+        if condition._key in self._store:
+            return self._store[condition._key][1]
+        complement = (~condition)._key
+        if complement in self._store:
+            return 1.0 - self._store[complement][1]
+        raise UndefinedProbabilityError(condition)
+
+    def __delitem__(self, condition: Condition) -> None:
+        condition = _as_condition(condition)
+        for key in (condition._key, (~condition)._key):
+            if key in self._store:
+                del self._store[key]
+                return
+        raise UndefinedProbabilityError(condition)
+
+    def __len__(self) -> int:
+        return len(self._store)
+
+    def __repr__(self) -> str:
+        if not self._store:
+            return "PrSpace with no probabilities assigned"
+        lines = [f"PrSpace with {len(self._store)} probabilit{'y' if len(self._store) == 1 else 'ies'}:"]
+        lines += [f"  Pr[{c}] = {p:.7g}" for c, p in self._store.values()]
+        return "\n".join(lines)
+
+
+def _as_condition(x: Any) -> Condition:
+    if isinstance(x, Condition):
+        return x
+    if isinstance(x, Event):
+        raise TypeError(f"index a PrSpace with a condition such as Pr[{x.label} == 0], not a bare Event")
+    raise TypeError(f"index a PrSpace with a condition such as Pr[X == 0], not {type(x).__name__}")
+
+
+def _as_probability(p: Any, condition: Condition) -> float:
+    if isinstance(p, bool) or not isinstance(p, numbers.Real):
+        raise TypeError(f"Pr[{condition}] must be a number, not {type(p).__name__}")
+    p = float(p)
+    if math.isnan(p) or not 0.0 <= p <= 1.0:
+        raise ValueError(f"Pr[{condition}] must be between 0 and 1, got {p}")
+    return p
+
+
+def _infer_name(event: Event, frame: FrameType) -> str | None:
+    for scope in (frame.f_locals, frame.f_globals):
+        for name, value in list(scope.items()):
+            if value is event:
+                return name
+    return None

prspace-0.1.0.dist-info/METADATA

@@ -0,0 +1,49 @@
+Metadata-Version: 2.5
+Name: prspace
+Version: 0.1.0
+Summary: Probability spaces with the same syntax in Python and R: Pr[X == 0] = 0.25
+Project-URL: Homepage, https://github.com/ivanharvard/prspace
+Project-URL: Issues, https://github.com/ivanharvard/prspace/issues
+Author-email: Ivan Gutierrez <gutierrezi0222@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: education,probability,statistics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# prspace
+
+Probability spaces with the same syntax in Python and R: `Pr[X == 0] = 0.25`.
+
+> **Alpha.** The API may change between 0.x releases.
+
+```python
+import math
+from prspace import PrSpace, Event
+
+n_samples = math.comb(19, 10)
+Pr = PrSpace()
+S_B = Event()
+
+for B in (100, 1000):
+    Pr[S_B == 0] = math.prod(1 - k / n_samples for k in range(B))
+    Pr[S_B >= 1] = 1 - Pr[S_B == 0]
+    print("Pr[S_B >= 1] =", Pr[S_B >= 1])
+
+print(Pr)
+# PrSpace with 2 probabilities:
+#   Pr[S_B == 0] = 0.004397413
+#   Pr[S_B >= 1] = 0.9956026
+```
+
+- Complements are derived: after `Pr[X == 0] = 0.25`, `Pr[X != 0]` and `Pr[~(X == 0)]` are `0.75`.
+- Reading a condition that was never assigned raises `UndefinedProbabilityError` (a `KeyError`).
+- Event names are inferred from the variable they're bound to, or pass `Event("name")`.
+
+The R package has the same syntax. See the [repository](https://github.com/ivanharvard/prspace)
+for both.

prspace-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+prspace/__init__.py,sha256=lU2iFMrsenOp7o-oUQKSYstrr_dFulMA4ESjNInE-ZY,241
+prspace/_core.py,sha256=i9_pMluzIwXkxUixX9hE6lJM840-Xb34Q0D5T0Ey9HY,6717
+prspace/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+prspace-0.1.0.dist-info/METADATA,sha256=uvORu0xXJpszKcMjTzCgF6cPBbjY9R8xFk0gnIjqVnI,1646
+prspace-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+prspace-0.1.0.dist-info/licenses/LICENSE,sha256=_M5dt9rPHP8uxoZKiTkgziXevqkBfoZzaBtb1_Bvd3Q,1071
+prspace-0.1.0.dist-info/RECORD,,

prspace-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

prspace-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Gutierrez
+
+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.