tether-references 0.1.0__tar.gz

tether_references-0.1.0/LICENSE

@@ -0,0 +1,3 @@
+
+    Tether  © 2026 by Jeff McAdams is licensed under CC BY-SA 4.0. To view a copy of this license, visit https://creativecommons.org/licenses/by-sa/4.0/
+    

tether_references-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: tether-references
+Version: 0.1.0
+Summary: Tether creates bidirectionally entangled object references
+Author: Jeff McAdams
+Author-email: Jeff McAdams <jeffmca@gmail.com>
+License-Expression: CC-BY-SA-4.0
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# Tether
+Tether is a small python library for managing bidirectionally related  object references.
+
+Thanks to Jeff Kala for coming up with the name, Tether, for this project. I suck at naming things and after a brief description, Jeff came up with the name, and I liked it, so this is now known as Tether. Jeff wins a mention here in the README for his naming cleverness. I'm just glad it came from another "Jeff".
+
+By example, if you have two classes, class A and class B, when you call tether's create_relation() with appropriate arguments, class A and class B will have attributes (actually properties) injected to reference one or more objects of the other type.
+
+The cardinality of the references can be either "one" or "many". If the cardinality of the reference is "many", the resulting attribute will be represented by a set-like object.
+
+More concretely, using one of the classic examples for OOP, if you have a class Car, and a class Engine, assuming a one-to-one relation, when you create_relation() specifying Car and Engine, class Car will gain an attribute engine that will return the associated Engine object, and class Engine will gain an attribute car that will return the associated Car object.
+
+	>>> from tether import create_relation
+	>>> 
+	>>> class Car:
+	...     single='car'
+	...     plural='cars'
+	...     
+	>>> class Engine:
+	...     single='engine'
+	...     plural='engines'
+	...     
+	>>> rel_car_engine = create_relation(name='car_engine', a_type=Car,	a_cardinality='one', b_type=Engine, b_cardinality='one')
+	>>> car1 = Car()
+	>>> engine1 = Engine()
+	
+	>>> print(car1.engine)
+	None
+	>>> print(engine1.car)
+	None
+	
+	>>> car1.engine = engine1
+	
+	>>> print(car1.engine)
+	<__main__.Engine object at 0x7cc87a398980>
+	>>> print(engine1.car)
+	<__main__.Car object at 0x7cc87a398830>
+	>>> 
+
+Let's change the Engine to EVMotor, so it makes sense to have a cardinality of "many":
+
+	>>> from tether import create_relation
+	>>> class Car:
+	...     single='car'
+	...     plural='cars'
+	...     
+	>>> class EVMotor:
+	...     single='evmotor'
+	...     plural='evmotors'
+	...     
+	>>> rel_car_evmotor = create_relation(name='car_evmotor', a_type=Car, a_cardinality='one', b_type=EVMotor, b_cardinality='many')
+	>>> 
+	>>> car1 = Car()
+	>>> evmotor1 = EVMotor()
+	>>> evmotor2 = EVMotor()
+	>>> 
+	>>> print(car1.evmotors)
+	set()
+	>>> print(evmotor1.car)
+	None
+	>>> print(evmotor2.car)
+	None
+
+	>>> evmotor1.car = car1
+	
+	>>> print(car1.evmotors)
+	{<__main__.EVMotor object at 0x7d60c059c980>}
+	>>> car1.evmotors.add(evmotor2)
+	>>> print(car1.evmotors)
+	{<__main__.EVMotor object at 0x7d60c059c980>, 	<__main__.EVMotor object at 0x7d60c06e6ad0>
+	>>> evmotor2.car
+	<__main__.Car object at 0x7d60c059c830>
+
+You can see that the "many" cardinality relation behaviors (mostly) as a set (at the time of this writing, not all set methods are implemented), but the bidirectional relationship is maintained.
+
+## Motivation
+See [Motivation.md](Motivation.md)

tether_references-0.1.0/README.md

@@ -0,0 +1,76 @@
+# Tether
+Tether is a small python library for managing bidirectionally related  object references.
+
+Thanks to Jeff Kala for coming up with the name, Tether, for this project. I suck at naming things and after a brief description, Jeff came up with the name, and I liked it, so this is now known as Tether. Jeff wins a mention here in the README for his naming cleverness. I'm just glad it came from another "Jeff".
+
+By example, if you have two classes, class A and class B, when you call tether's create_relation() with appropriate arguments, class A and class B will have attributes (actually properties) injected to reference one or more objects of the other type.
+
+The cardinality of the references can be either "one" or "many". If the cardinality of the reference is "many", the resulting attribute will be represented by a set-like object.
+
+More concretely, using one of the classic examples for OOP, if you have a class Car, and a class Engine, assuming a one-to-one relation, when you create_relation() specifying Car and Engine, class Car will gain an attribute engine that will return the associated Engine object, and class Engine will gain an attribute car that will return the associated Car object.
+
+	>>> from tether import create_relation
+	>>> 
+	>>> class Car:
+	...     single='car'
+	...     plural='cars'
+	...     
+	>>> class Engine:
+	...     single='engine'
+	...     plural='engines'
+	...     
+	>>> rel_car_engine = create_relation(name='car_engine', a_type=Car,	a_cardinality='one', b_type=Engine, b_cardinality='one')
+	>>> car1 = Car()
+	>>> engine1 = Engine()
+	
+	>>> print(car1.engine)
+	None
+	>>> print(engine1.car)
+	None
+	
+	>>> car1.engine = engine1
+	
+	>>> print(car1.engine)
+	<__main__.Engine object at 0x7cc87a398980>
+	>>> print(engine1.car)
+	<__main__.Car object at 0x7cc87a398830>
+	>>> 
+
+Let's change the Engine to EVMotor, so it makes sense to have a cardinality of "many":
+
+	>>> from tether import create_relation
+	>>> class Car:
+	...     single='car'
+	...     plural='cars'
+	...     
+	>>> class EVMotor:
+	...     single='evmotor'
+	...     plural='evmotors'
+	...     
+	>>> rel_car_evmotor = create_relation(name='car_evmotor', a_type=Car, a_cardinality='one', b_type=EVMotor, b_cardinality='many')
+	>>> 
+	>>> car1 = Car()
+	>>> evmotor1 = EVMotor()
+	>>> evmotor2 = EVMotor()
+	>>> 
+	>>> print(car1.evmotors)
+	set()
+	>>> print(evmotor1.car)
+	None
+	>>> print(evmotor2.car)
+	None
+
+	>>> evmotor1.car = car1
+	
+	>>> print(car1.evmotors)
+	{<__main__.EVMotor object at 0x7d60c059c980>}
+	>>> car1.evmotors.add(evmotor2)
+	>>> print(car1.evmotors)
+	{<__main__.EVMotor object at 0x7d60c059c980>, 	<__main__.EVMotor object at 0x7d60c06e6ad0>
+	>>> evmotor2.car
+	<__main__.Car object at 0x7d60c059c830>
+
+You can see that the "many" cardinality relation behaviors (mostly) as a set (at the time of this writing, not all set methods are implemented), but the bidirectional relationship is maintained.
+
+## Motivation
+See [Motivation.md](Motivation.md)

tether_references-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "tether-references"
+version = "0.1.0"
+description = "Tether creates bidirectionally entangled object references"
+readme = "README.md"
+authors = [
+    { name = "Jeff McAdams", email = "jeffmca@gmail.com" }
+]
+requires-python = ">=3.14"
+dependencies = []
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha"
+]
+license = "CC-BY-SA-4.0"
+license-files = ["LICENSE"]
+
+[build-system]
+requires = ["uv_build>=0.9.22,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true

tether_references-0.1.0/src/tether_references/__init__.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+from functools import partial
+from typing import Any, Literal
+
+
+Cardinality = Literal['one', 'many']
+#T = TypeVar('T')
+#U = TypeVar('U')
+#V = TypeVar('V')
+
+
+def _get_relation(self, *, relreg: RelationRegistry):
+    # naive implementation that searches through the relmgr's set of relation
+    # tuples until we find self._me. Return the related item
+    for rel in relreg.items:
+        if rel[0] == self:
+            return rel[1]
+        elif rel[1] == self:
+            return rel[0]
+    return None
+
+def _set_relation(self, value: Any, *, relreg: RelationRegistry):
+    for rel in set(relreg.items):
+        if rel[0] == self:
+            relreg.items.remove(rel)
+        if rel[1] == self:
+            relreg.items.remove(rel)
+    me_type = type(self)
+    if relreg.a_type == me_type:
+        relreg.items.add((self, value))
+    elif relreg.b_type == me_type:
+        relreg.items.add((value, self))
+
+def _del_relation(self, *, relreg: RelationRegistry):
+    for rel in set(relreg.items):
+        if rel[0] == self:
+            relreg.items.remove(rel)
+        elif rel[1] == self:
+            relreg.items.remove(rel)
+
+def _get_relationset(self, *, relreg: RelationRegistry):
+    relset = RelationSet(relreg=relreg, srcitem=self)
+    return relset
+
+class RelationSet:
+    def __init__(self, relreg: RelationRegistry, srcitem: Any) -> None:
+        self._srcitem = srcitem
+        self._relmgr = relreg
+        self._iternum = 0
+
+    def __and__(self):
+        raise NotImplementedError()
+
+    def __contains__(self, other_item: Any) -> bool:
+        if (self._srcitem, other_item) in self._relmgr.items:
+            return True
+        elif (other_item, self._srcitem) in self._relmgr.items:
+            return True
+        else:
+            return False
+
+    def __eq__(self, other) -> bool:
+        for x in self:
+            if x not in other:
+                return False
+        for x in other:
+            if x not in self:
+                return False
+        return True
+
+    def __iter__(self) -> RelationSet:
+        return self
+
+    def __next__(self):
+        cur = 0
+        for iteritem in self._relmgr.items:
+            if cur < self._iternum:
+                cur += 1
+                continue
+            if self._srcitem is iteritem[0]:
+                self._iternum += 1
+                cur += 1
+                return iteritem[1]
+            elif self._srcitem is iteritem[1]:
+                self._iternum += 1
+                cur += 1
+                return iteritem[0]
+        raise StopIteration
+
+
+    def __len__(self) -> int:
+        count = 0
+        for iteritem in self._relmgr.items:
+            if self._srcitem is iteritem[0]:
+                count += 1
+            elif self._srcitem is iteritem[1]:
+                count += 1
+        return count
+
+    def __repr__(self):
+        x = (set(self))
+        return str(x)
+
+    def __str__(self):
+        return self.__repr__()
+
+    def add(self, value):
+        if type(self._srcitem) == self._relmgr.a_type:
+            if type(value) != self._relmgr.b_type:
+                raise TypeError()
+            self._relmgr.items.add((self._srcitem, value))
+        elif type(self._srcitem) == self._relmgr.b_type:
+            if type(value) != self._relmgr.a_type:
+                raise TypeError()
+            self._relmgr.items.add((value, self._srcitem))
+
+    def clear(self):
+        raise NotImplementedError()
+
+    def copy(self):
+        raise NotImplementedError()
+
+    def difference(self):
+        raise NotImplementedError()
+
+    def difference_update(self):
+        raise NotImplementedError()
+
+    def discard(self, value):
+        if type(self._srcitem) == self._relmgr.a_type:
+            self._relmgr.items.discard((self._srcitem, value))
+        elif type(self._srcitem) == self._relmgr.b_type:
+            self._relmgr.items.discard((value, self._srcitem))
+
+    def intersection(self):
+        raise NotImplementedError()
+
+    def intersection_update(self):
+        raise NotImplementedError()
+
+    def isdisjoint(self):
+        raise NotImplementedError()
+
+    def issubset(self):
+        raise NotImplementedError()
+
+    def issuperset(self):
+        raise NotImplementedError()
+
+    def pop(self, index: int = None):
+        raise NotImplementedError()
+
+    def remove(self, value):
+        if type(self._srcitem) == self._relmgr.a_type:
+            if (self._srcitem, value) not in self._relmgr.items:
+                raise KeyError(value)
+        elif type(self._srcitem) == self._relmgr.b_type:
+            if (value, self._srcitem) not in self._relmgr.items:
+                raise KeyError(value)
+
+        if type(self._srcitem) == self._relmgr.a_type:
+            self._relmgr.items.discard((self._srcitem, value))
+        elif type(self._srcitem) == self._relmgr.b_type:
+            self._relmgr.items.discard((value, self._srcitem))
+
+    def symmetric_difference(self):
+        raise NotImplementedError()
+
+    def symmetric_difference_update(self):
+        raise NotImplementedError()
+
+    def union(self):
+        raise NotImplementedError()
+
+    def update(self):
+        raise NotImplementedError()
+
+
+class RelationRegistry:
+    def __init__(self,
+                 name: str,
+                 a_type: Any,
+                 a_cardinality: Cardinality,
+                 b_type: Any,
+                 b_cardinality: Cardinality,
+                 dependancy: bool = False
+    ) -> None:
+        self.name: str = name
+        self.items: set[tuple[Any, Any]] = set()
+        self.a_type: Any = a_type
+        self.a_cardinality: Cardinality = a_cardinality
+        self.b_type: Any = b_type
+        self.b_cardinality: Cardinality = b_cardinality
+        self.dependancy: bool = dependancy
+
+
+def create_relation(name: str,
+                    a_type: Any,
+                    a_cardinality: Cardinality,
+                    b_type: Any,
+                    b_cardinality: Cardinality,
+                    a_attrname: str = '',
+                    b_attrname: str = '',
+                    dependancy: bool = False
+                    ) -> RelationRegistry:
+    relreg = RelationRegistry(name=name,
+                              a_type=a_type,
+                              a_cardinality=a_cardinality,
+                              b_type=b_type,
+                              b_cardinality=b_cardinality,
+                              dependancy=dependancy
+                              )
+    if a_cardinality == 'one':
+        get_part = partial(_get_relation, relreg=relreg)
+        set_part = partial(_set_relation, relreg=relreg)
+        del_part = partial(_del_relation, relreg=relreg)
+        prop = property(get_part, set_part, del_part)
+        if a_attrname == '':
+            setattr(b_type, a_type.single, prop)
+        else:
+            setattr(b_type, a_attrname, prop)
+    elif a_cardinality == 'many':
+        get_part = partial(_get_relationset, relreg=relreg)
+        prop = property(get_part)
+        if a_attrname == '':
+            setattr(b_type, a_type.plural, prop)
+        else:
+            setattr(b_type, a_attrname, prop)
+    if b_cardinality == 'one':
+        get_part = partial(_get_relation, relreg=relreg)
+        set_part = partial(_set_relation, relreg=relreg)
+        del_part = partial(_del_relation, relreg=relreg)
+        prop = property(get_part, set_part, del_part)
+        if b_attrname == '':
+            setattr(a_type, b_type.single, prop)
+        else:
+            setattr(a_type, b_attrname, prop)
+    elif b_cardinality == 'many':
+        get_part = partial(_get_relationset, relreg=relreg)
+        prop = property(get_part)
+        if b_attrname == '':
+            setattr(a_type, b_type.plural, prop)
+        else:
+            setattr(a_type, b_attrname, prop)
+
+    return relreg
+
+#def get_relations(self, registry: RelationRegistry) -> Iterable:
+#    if type(self) == registry.a_type:
+#        key: str = 'a'
+#        value: str = 'b'
+#        cardinality: Cardinality = registry.a_cardinality
+#    else:
+#        key: str = 'b'
+#        value: str = 'a'
+#        cardinality: Cardinality = registry.b_cardinality
+#    for item in registry.items:
+#        if getattr(item, key) == self:
+#            if cardinality == 'one':
+#                return getattr(item, value)
+#            elif cardinality == 'many':
+#                yield getattr(item, value)
+#    if cardinality == 'one':
+#        return None