opticol 0.1.0a1__tar.gz

opticol-0.1.0a1/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: opticol
+Version: 0.1.0a1
+Summary: Implementations for the various Python Collection ABCs that optimize along various axes.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+## Opticol
+
+Optimized collections (hence *opticol*) for Python. This package provides memory optimized versions of the base Python collection types which are:
+
+* (Mutable)Sequence
+* (Mutable)Mapping
+* (Mutable)Set
+
+The insight behind the package is the following: the size of an empty set is 216 bytes (on Python 3.14) but the size of an empty object with an empty __slots__ member is only 32 bytes. Python programs that hold large datasets in memory could benefit from using these optimized collections which fully implement the respective collection ABCs, but at a fraction of the runtime memory.
+
+So for general users these optimizations will not be worth if if the dataset being used comfortably fits in memory, but applications which currently create tens or hundreds of thousand of Python objects could dramatically lower memory usage without API changes.
+
+## Usage
+
+The optimized classes could be used directly, by creating an EmptySequence directly for example, but the recommended usage is to use the collection level `project` method which tries to project a collection instance into the memory optimized variants automatically. Additionally, there is a factory interface that could be plugged in to allow for different strategies beyond the typical `project` logic.
+
+Consider the following example:
+
+```
+import opticol
+
+optimized_list = opticol.seq_project([]) # Actually an instance of EmptySequence
+optimized_list_single = opticol.mut_seq_project(("MyString",)) # Actually an instance of Small1MutableSequence
+```
+
+A small note that in the current implementation, optimization is only in one direction. That is, if the MutableSequence type is optimized for collections of size 0, 1, 2, 3, then once an operation pushes it past into size 4, further decreasing of the size will not restore the optimization.

opticol-0.1.0a1/README.md

@@ -0,0 +1,26 @@
+## Opticol
+
+Optimized collections (hence *opticol*) for Python. This package provides memory optimized versions of the base Python collection types which are:
+
+* (Mutable)Sequence
+* (Mutable)Mapping
+* (Mutable)Set
+
+The insight behind the package is the following: the size of an empty set is 216 bytes (on Python 3.14) but the size of an empty object with an empty __slots__ member is only 32 bytes. Python programs that hold large datasets in memory could benefit from using these optimized collections which fully implement the respective collection ABCs, but at a fraction of the runtime memory.
+
+So for general users these optimizations will not be worth if if the dataset being used comfortably fits in memory, but applications which currently create tens or hundreds of thousand of Python objects could dramatically lower memory usage without API changes.
+
+## Usage
+
+The optimized classes could be used directly, by creating an EmptySequence directly for example, but the recommended usage is to use the collection level `project` method which tries to project a collection instance into the memory optimized variants automatically. Additionally, there is a factory interface that could be plugged in to allow for different strategies beyond the typical `project` logic.
+
+Consider the following example:
+
+```
+import opticol
+
+optimized_list = opticol.seq_project([]) # Actually an instance of EmptySequence
+optimized_list_single = opticol.mut_seq_project(("MyString",)) # Actually an instance of Small1MutableSequence
+```
+
+A small note that in the current implementation, optimization is only in one direction. That is, if the MutableSequence type is optimized for collections of size 0, 1, 2, 3, then once an operation pushes it past into size 4, further decreasing of the size will not restore the optimization.

opticol-0.1.0a1/opticol/__init__.py

@@ -0,0 +1,27 @@
+__all__ = [
+    "mapping",
+    "mutable_mapping",
+    "mutable_sequence",
+    "mutable_set",
+    "projector",
+    "sequence",
+    "set",
+]
+
+from opticol import mutable_mapping, mutable_sequence, mutable_set, sequence
+from opticol import mapping as _mapping_module
+from opticol import set as _set_module
+
+mapping = _mapping_module.project
+mut_mapping = mutable_mapping.project
+mut_seq = mutable_sequence.project
+mut_set = mutable_set.project
+seq = sequence.project
+set = _set_module.project
+
+del _mapping_module
+del mutable_mapping
+del mutable_sequence
+del mutable_set
+del sequence
+del _set_module

opticol-0.1.0a1/opticol/_mapping.py

@@ -0,0 +1,165 @@
+from abc import ABCMeta
+from collections.abc import Sequence
+from itertools import zip_longest
+from typing import Any
+
+
+class OptimizedMappingMeta(ABCMeta):
+    def __new__(
+        mcs,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, Any],
+        *,
+        internal_size: int,
+    ) -> type:
+        slots = tuple(f"_item{i}" for i in range(internal_size))
+        namespace["__slots__"] = slots
+
+        mcs._add_methods(slots, namespace, internal_size)
+
+        return super().__new__(mcs, name, bases, namespace)
+
+    @staticmethod
+    def _add_methods(
+        item_slots: Sequence[str],
+        namespace: dict[str, Any],
+        internal_size: int,
+    ) -> None:
+        if internal_size > 0:
+            init_ir = f"""
+def __init__(self, {",".join(item_slots)}):
+    {"\n    ".join(f"self.{slot} = {slot}" for slot in item_slots)}
+"""
+            exec(init_ir, namespace)
+
+        def __getitem__(self, key):
+            for slot in item_slots:
+                item = getattr(self, slot)
+                if item[0] == key:
+                    return item[1]
+            raise KeyError(key)
+
+        def __iter__(self):
+            yield from (getattr(self, slot)[0] for slot in item_slots)
+
+        def __len__(_):
+            return internal_size
+
+        def __repr__(self):
+            items = [
+                f"{repr(getattr(self, slot)[0])}: {repr(getattr(self, slot)[1])}"
+                for slot in item_slots
+            ]
+            return f"{{{", ".join(items)}}}"
+
+        namespace["__getitem__"] = __getitem__
+        namespace["__iter__"] = __iter__
+        namespace["__len__"] = __len__
+        namespace["__repr__"] = __repr__
+
+
+class OptimizedMutableMappingMeta(ABCMeta):
+    def __new__(
+        mcs,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, Any],
+        *,
+        internal_size: int,
+    ) -> type:
+        if internal_size <= 0:
+            raise ValueError(f"{internal_size} is not a valid size for the MutableMapping type.")
+
+        slots = tuple(f"_item{i}" for i in range(internal_size))
+        namespace["__slots__"] = slots
+
+        mcs._add_methods(slots, namespace, internal_size)
+
+        return super().__new__(mcs, name, bases, namespace)
+
+    @staticmethod
+    def _add_methods(
+        item_slots: Sequence[str],
+        namespace: dict[str, Any],
+        internal_size: int,
+    ) -> None:
+        def _assign_dict(self, d):
+            if len(d) > internal_size:
+                setattr(self, item_slots[0], d)
+                for slot in item_slots[1:]:
+                    setattr(self, slot, None)
+            else:
+                sentinel = object()
+                for pair, slot in zip_longest(d.items(), item_slots, fillvalue=sentinel):
+                    if pair is sentinel:
+                        setattr(self, slot, None)
+                    else:
+                        setattr(self, slot, pair)
+
+        def __init__(self, it):
+            d = it if isinstance(it, dict) else dict(it)
+            _assign_dict(self, d)
+
+        def __getitem__(self, key):
+            first = getattr(self, item_slots[0])
+            if isinstance(first, dict):
+                return first[key]
+
+            for slot in item_slots:
+                item = getattr(self, slot)
+                if item is None:
+                    break
+
+                if item[0] == key:
+                    return item[1]
+
+            raise KeyError(key)
+
+        def __setitem__(self, key, value):
+            current = dict(self)
+            current[key] = value
+            _assign_dict(self, current)
+
+        def __delitem__(self, key):
+            current = dict(self)
+            del current[key]
+            _assign_dict(self, current)
+
+        def __iter__(self):
+            first = getattr(self, item_slots[0])
+            if isinstance(first, dict):
+                yield from first
+                return
+
+            for slot in item_slots:
+                item = getattr(self, slot)
+                if item is None:
+                    return
+
+                yield item[0]
+
+        def __len__(self):
+            first = getattr(self, item_slots[0])
+            if isinstance(first, dict):
+                return len(first)
+
+            count = 0
+            for slot in item_slots:
+                if getattr(self, slot) is None:
+                    break
+                count += 1
+
+            return count
+
+        def __repr__(self):
+            items = [f"{repr(k)}: {repr(v)}" for k, v in self.items()]
+            return f"{{{", ".join(items)}}}"
+
+        namespace["__init__"] = __init__
+        namespace["__getitem__"] = __getitem__
+        namespace["__setitem__"] = __setitem__
+        namespace["__delitem__"] = __delitem__
+        namespace["__iter__"] = __iter__
+        namespace["__len__"] = __len__
+        namespace["__repr__"] = __repr__

opticol-0.1.0a1/opticol/_sentinel.py

@@ -0,0 +1,13 @@
+from dataclasses import dataclass
+from typing import Any
+
+
+class EndMarker: ...
+
+
+END = EndMarker()
+
+
+@dataclass(slots=True, frozen=True)
+class Overflow:
+    data: Any

opticol-0.1.0a1/opticol/_sequence.py

@@ -0,0 +1,179 @@
+from abc import ABCMeta
+from itertools import zip_longest
+from typing import Any, Callable
+
+from collections.abc import Sequence
+
+from opticol._sentinel import END, Overflow
+
+
+def _adjust_index(idx: int, length: int) -> int:
+    adjusted = idx if idx >= 0 else length + idx
+    if adjusted < 0 or adjusted >= length:
+        raise IndexError(f"{adjusted} is outside of the expected bounds.")
+    return adjusted
+
+
+class OptimizedSequenceMeta(ABCMeta):
+    def __new__(
+        mcs,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, Any],
+        *,
+        internal_size: int,
+        project: Callable[[list], Sequence],
+    ) -> type:
+        slots = tuple(f"_item{i}" for i in range(internal_size))
+        namespace["__slots__"] = slots
+
+        mcs._add_methods(slots, namespace, internal_size, project)
+
+        return super().__new__(mcs, name, bases, namespace)
+
+    @staticmethod
+    def _add_methods(
+        item_slots: Sequence[str],
+        namespace: dict[str, Any],
+        internal_size: int,
+        project: Callable[[list], Sequence],
+    ) -> None:
+        if internal_size > 0:
+            init_ir = f"""
+def __init__(self, {",".join(item_slots)}):
+    {"\n    ".join(f"self.{slot} = {slot}" for slot in item_slots)}
+"""
+            exec(init_ir, namespace)
+
+        def __getitem__(self, key):
+            match key:
+                case int():
+                    key = _adjust_index(key, len(self))
+                    return getattr(self, item_slots[key])
+                case slice():
+                    indices = range(*key.indices(len(self)))
+                    return project([self[i] for i in indices])
+                case _:
+                    raise TypeError(
+                        f"Sequence accessors must be integers or slices, not {type(key)}"
+                    )
+
+        def __len__(_):
+            return internal_size
+
+        def __repr__(self):
+            return f"[{", ".join(repr(getattr(self, slot)) for slot in item_slots)}]"
+
+        namespace["__getitem__"] = __getitem__
+        namespace["__len__"] = __len__
+        namespace["__repr__"] = __repr__
+
+
+class OptimizedMutableSequenceMeta(ABCMeta):
+    def __new__(
+        mcs,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, Any],
+        *,
+        internal_size: int,
+        project: Callable[[list], Sequence],
+    ) -> type:
+        if internal_size <= 0:
+            raise ValueError(f"{internal_size} is not a valid size for the MutableSequence type.")
+
+        slots = tuple(f"_item{i}" for i in range(internal_size))
+        namespace["__slots__"] = slots
+
+        mcs._add_methods(slots, namespace, internal_size, project)
+
+        return super().__new__(mcs, name, bases, namespace)
+
+    @staticmethod
+    def _add_methods(
+        item_slots: Sequence[str],
+        namespace: dict[str, Any],
+        internal_size: int,
+        project: Callable[[list], Sequence],
+    ) -> None:
+        def _assign_list(self, l):
+            if len(l) > internal_size:
+                setattr(self, item_slots[0], Overflow(l))
+                for slot in item_slots[1:]:
+                    setattr(self, slot, END)
+            else:
+                sentinel = object()
+                for slot, v in zip_longest(item_slots, l, fillvalue=sentinel):
+                    if v is sentinel:
+                        setattr(self, slot, END)
+                    else:
+                        setattr(self, slot, v)
+
+        def __init__(self, it):
+            collected = it if isinstance(it, list) else list(it)
+            _assign_list(self, collected)
+
+        def __getitem__(self, key):
+            first = getattr(self, item_slots[0])
+            overflowed = isinstance(first, Overflow)
+
+            match key:
+                case int():
+                    if overflowed:
+                        return first.data[key]
+
+                    key = _adjust_index(key, len(self))
+                    v = getattr(self, item_slots[key])
+                    if v is END:
+                        raise IndexError(f"{key} is outside of the expected bounds.")
+                    return v
+                case slice():
+                    if overflowed:
+                        return project(first.data[key])
+
+                    indices = range(*key.indices(len(self)))
+                    first = getattr(self, item_slots[0])
+                    return project([self[i] for i in indices])
+                case _:
+                    raise TypeError(
+                        f"Sequence accessors must be integers or slices, not {type(key)}"
+                    )
+
+        def __setitem__(self, key, value):
+            current = list(self)
+            current[key] = value
+            _assign_list(self, current)
+
+        def __delitem__(self, key):
+            current = list(self)
+            del current[key]
+            _assign_list(self, current)
+
+        def __len__(self):
+            first = getattr(self, item_slots[0])
+            if isinstance(first, Overflow):
+                return len(first.data)
+
+            count = 0
+            for slot in item_slots:
+                if getattr(self, slot) is END:
+                    break
+                count += 1
+
+            return count
+
+        def insert(self, index, value):
+            current = list(self)
+            current.insert(index, value)
+            _assign_list(self, current)
+
+        def __repr__(self):
+            return f"[{", ".join(repr(val) for val in self)}]"
+
+        namespace["__init__"] = __init__
+        namespace["__getitem__"] = __getitem__
+        namespace["__setitem__"] = __setitem__
+        namespace["__delitem__"] = __delitem__
+        namespace["__len__"] = __len__
+        namespace["insert"] = insert
+        namespace["__repr__"] = __repr__

opticol-0.1.0a1/opticol/_set.py

@@ -0,0 +1,176 @@
+from abc import ABCMeta
+from itertools import zip_longest
+from typing import Any, Callable
+
+from collections.abc import Sequence, Set
+
+from opticol._sentinel import END, Overflow
+
+
+class OptimizedSetMeta(ABCMeta):
+    def __new__(
+        mcs,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, Any],
+        *,
+        internal_size: int,
+        project: Callable[[set], Set],
+    ) -> type:
+        slots = tuple(f"_item{i}" for i in range(internal_size))
+        namespace["__slots__"] = slots
+
+        mcs._add_methods(slots, namespace, internal_size, project)
+
+        return super().__new__(mcs, name, bases, namespace)
+
+    @staticmethod
+    def _add_methods(
+        item_slots: Sequence[str],
+        namespace: dict[str, Any],
+        internal_size: int,
+        project: Callable[[set], Set],
+    ) -> None:
+        if internal_size > 0:
+            init_ir = f"""
+def __init__(self, {",".join(item_slots)}):
+    {"\n    ".join(f"self.{slot} = {slot}" for slot in item_slots)}
+"""
+            exec(init_ir, namespace)
+
+        def __contains__(self, value):
+            for slot in item_slots:
+                if getattr(self, slot) == value:
+                    return True
+            return False
+
+        def __iter__(self):
+            for slot in item_slots:
+                yield getattr(self, slot)
+
+        def __len__(_):
+            return internal_size
+
+        def __repr__(self):
+            if internal_size == 0:
+                return "set()"
+            return f"{{{", ".join(repr(getattr(self, slot)) for slot in item_slots)}}}"
+
+        def _from_iterable(_, it):
+            return project(set(it))
+
+        namespace["__contains__"] = __contains__
+        namespace["__iter__"] = __iter__
+        namespace["__len__"] = __len__
+        namespace["__repr__"] = __repr__
+        namespace["_from_iterable"] = classmethod(_from_iterable)
+
+
+class OptimizedMutableSetMeta(ABCMeta):
+    def __new__(
+        mcs,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, Any],
+        *,
+        internal_size: int,
+        project: Callable[[set], Set],
+    ) -> type:
+        if internal_size <= 0:
+            raise ValueError(f"{internal_size} is not a valid size for the MutableSet type.")
+
+        slots = tuple(f"_item{i}" for i in range(internal_size))
+        namespace["__slots__"] = slots
+
+        mcs._add_methods(slots, namespace, internal_size, project)
+
+        return super().__new__(mcs, name, bases, namespace)
+
+    @staticmethod
+    def _add_methods(
+        item_slots: Sequence[str],
+        namespace: dict[str, Any],
+        internal_size: int,
+        project: Callable[[set], Set],
+    ) -> None:
+        def _assign_set(self, s):
+            if len(s) > internal_size:
+                setattr(self, item_slots[0], Overflow(s))
+                for slot in item_slots[1:]:
+                    setattr(self, slot, END)
+            else:
+                sentinel = object()
+                for slot, v in zip_longest(item_slots, s, fillvalue=sentinel):
+                    if v is sentinel:
+                        setattr(self, slot, END)
+                    else:
+                        setattr(self, slot, v)
+
+        def __init__(self, it):
+            collected = it if isinstance(it, set) else set(it)
+            _assign_set(self, collected)
+
+        def __contains__(self, value):
+            first = getattr(self, item_slots[0])
+            if isinstance(first, Overflow):
+                return value in first.data
+
+            for slot in item_slots:
+                v = getattr(self, slot)
+                if v is END:
+                    break
+                if v == value:
+                    return True
+            return False
+
+        def __iter__(self):
+            first = getattr(self, item_slots[0])
+            if isinstance(first, Overflow):
+                yield from first.data
+                return
+
+            for slot in item_slots:
+                v = getattr(self, slot)
+                if v is END:
+                    break
+                yield v
+
+        def __len__(self):
+            first = getattr(self, item_slots[0])
+            if isinstance(first, Overflow):
+                return len(first.data)
+
+            count = 0
+            for slot in item_slots:
+                if getattr(self, slot) is END:
+                    break
+                count += 1
+
+            return count
+
+        def add(self, value):
+            current = set(self)
+            current.add(value)
+            _assign_set(self, current)
+
+        def discard(self, value):
+            current = set(self)
+            current.discard(value)
+            _assign_set(self, current)
+
+        def __repr__(self):
+            if len(self) == 0:
+                return "set()"
+            return f"{{{", ".join(repr(val) for val in self)}}}"
+
+        def _from_iterable(_, it):
+            return project(set(it))
+
+        namespace["__init__"] = __init__
+        namespace["__contains__"] = __contains__
+        namespace["__iter__"] = __iter__
+        namespace["__len__"] = __len__
+        namespace["add"] = add
+        namespace["discard"] = discard
+        namespace["__repr__"] = __repr__
+        namespace["_from_iterable"] = classmethod(_from_iterable)

opticol-0.1.0a1/opticol/mapping.py

@@ -0,0 +1,26 @@
+from collections.abc import Mapping
+from opticol._mapping import OptimizedMappingMeta
+
+
+def _create_mapping_class(size: int) -> type:
+    return OptimizedMappingMeta(f"_Size{size}Mapping", (Mapping,), {}, internal_size=size)
+
+
+_by_size: list[type] = []
+
+
+def project[K, V](original: Mapping[K, V]) -> Mapping[K, V]:
+    if len(original) >= len(_by_size):
+        return original
+
+    ctor = _by_size[len(original)]
+    items = tuple(original.items())
+    return ctor(*items)
+
+
+_Size0Mapping = _create_mapping_class(0)
+_Size1Mapping = _create_mapping_class(1)
+_Size2Mapping = _create_mapping_class(2)
+_Size3Mapping = _create_mapping_class(3)
+
+_by_size.extend([_Size0Mapping, _Size1Mapping, _Size2Mapping, _Size3Mapping])

opticol-0.1.0a1/opticol/mutable_mapping.py

@@ -0,0 +1,31 @@
+from collections.abc import MutableMapping
+from opticol._mapping import OptimizedMutableMappingMeta
+
+
+def _create_mut_mapping_class(size: int) -> type:
+    return OptimizedMutableMappingMeta(
+        f"_Size{size}MutableMapping",
+        (MutableMapping,),
+        {},
+        internal_size=size,
+    )
+
+
+_by_size: list[type] = []
+
+
+def project[K, V](original: MutableMapping[K, V]) -> MutableMapping[K, V]:
+    if len(original) >= len(_by_size):
+        return original
+
+    ctor = _by_size[len(original)]
+    return ctor(original)
+
+
+_Size1MutableMapping = _create_mut_mapping_class(1)
+_Size2MutableMapping = _create_mut_mapping_class(2)
+_Size3MutableMapping = _create_mut_mapping_class(3)
+
+_by_size.extend(
+    [_Size1MutableMapping, _Size1MutableMapping, _Size2MutableMapping, _Size3MutableMapping]
+)

opticol-0.1.0a1/opticol/mutable_sequence.py

@@ -0,0 +1,32 @@
+from collections.abc import MutableSequence
+from opticol._sequence import OptimizedMutableSequenceMeta
+
+
+def _create_mut_seq_class(size: int) -> type:
+    return OptimizedMutableSequenceMeta(
+        f"_Size{size}MutableSequence",
+        (MutableSequence,),
+        {},
+        internal_size=size,
+        project=project,
+    )
+
+
+_by_size: list[type] = []
+
+
+def project[T](original: MutableSequence[T]) -> MutableSequence[T]:
+    if len(original) >= len(_by_size):
+        return original
+
+    ctor = _by_size[len(original)]
+    return ctor(original)
+
+
+_Size1MutableSequence = _create_mut_seq_class(1)
+_Size2MutableSequence = _create_mut_seq_class(2)
+_Size3MutableSequence = _create_mut_seq_class(3)
+
+_by_size.extend(
+    [_Size1MutableSequence, _Size1MutableSequence, _Size2MutableSequence, _Size3MutableSequence]
+)

opticol-0.1.0a1/opticol/mutable_set.py

@@ -0,0 +1,30 @@
+from collections.abc import MutableSet
+from opticol._set import OptimizedMutableSetMeta
+
+
+def _create_mut_set_class(size: int) -> type:
+    return OptimizedMutableSetMeta(
+        f"_Size{size}MutableSet",
+        (MutableSet,),
+        {},
+        internal_size=size,
+        project=project,
+    )
+
+
+_by_size: list[type] = []
+
+
+def project[T](original: MutableSet[T]) -> MutableSet[T]:
+    if len(original) >= len(_by_size):
+        return original
+
+    ctor = _by_size[len(original)]
+    return ctor(original)
+
+
+_Size1MutableSet = _create_mut_set_class(1)
+_Size2MutableSet = _create_mut_set_class(2)
+_Size3MutableSet = _create_mut_set_class(3)
+
+_by_size.extend([_Size1MutableSet, _Size1MutableSet, _Size2MutableSet, _Size3MutableSet])

opticol-0.1.0a1/opticol/projector.py

@@ -0,0 +1,64 @@
+from abc import ABC, abstractmethod
+from collections.abc import Mapping, MutableMapping, MutableSequence, MutableSet, Sequence, Set
+
+import opticol
+
+
+class Projector(ABC):
+    @abstractmethod
+    def seq[T](self, seq: Sequence[T]) -> Sequence[T]: ...
+
+    @abstractmethod
+    def mut_seq[T](self, mut_seq: MutableSequence[T]) -> MutableSequence[T]: ...
+
+    @abstractmethod
+    def set[T](self, s: Set[T]) -> Set[T]: ...
+
+    @abstractmethod
+    def mut_set[T](self, mut_set: MutableSet[T]) -> MutableSet[T]: ...
+
+    @abstractmethod
+    def mapping[K, V](self, mapping: Mapping[K, V]) -> Mapping[K, V]: ...
+
+    @abstractmethod
+    def mut_mapping[K, V](self, mut_mapping: MutableMapping[K, V]) -> MutableMapping[K, V]: ...
+
+
+class PassThroughProjector(ABC):
+    def seq[T](self, seq: Sequence[T]) -> Sequence[T]:
+        return seq
+
+    def mut_seq[T](self, mut_seq: MutableSequence[T]) -> MutableSequence[T]:
+        return mut_seq
+
+    def set[T](self, s: Set[T]) -> Set[T]:
+        return s
+
+    def mut_set[T](self, mut_set: MutableSet[T]) -> MutableSet[T]:
+        return mut_set
+
+    def mapping[K, V](self, mapping: Mapping[K, V]) -> Mapping[K, V]:
+        return mapping
+
+    def mut_mapping[K, V](self, mut_mapping: MutableMapping[K, V]) -> MutableMapping[K, V]:
+        return mut_mapping
+
+
+class DefaultOptimizingProjector(Projector):
+    def seq[T](self, seq: Sequence[T]) -> Sequence[T]:
+        return opticol.seq(seq)
+
+    def mut_seq[T](self, mut_seq: MutableSequence[T]) -> MutableSequence[T]:
+        return opticol.mut_seq(mut_seq)
+
+    def set[T](self, s: Set[T]) -> Set[T]:
+        return opticol.set(s)
+
+    def mut_set[T](self, mut_set: MutableSet[T]) -> MutableSet[T]:
+        return opticol.mut_set(mut_set)
+
+    def mapping[K, V](self, mapping: Mapping[K, V]) -> Mapping[K, V]:
+        return opticol.mapping(mapping)
+
+    def mut_mapping[K, V](self, mut_mapping: MutableMapping[K, V]) -> MutableMapping[K, V]:
+        return opticol.mut_mapping(mut_mapping)

opticol-0.1.0a1/opticol/sequence.py

@@ -0,0 +1,27 @@
+from collections.abc import Sequence
+from opticol._sequence import OptimizedSequenceMeta
+
+
+def _create_seq_class(size: int) -> type:
+    return OptimizedSequenceMeta(
+        f"_Size{size}Sequence", (Sequence,), {}, internal_size=size, project=project
+    )
+
+
+_by_size: list[type] = []
+
+
+def project[T](original: Sequence[T]) -> Sequence[T]:
+    if len(original) >= len(_by_size):
+        return original
+
+    ctor = _by_size[len(original)]
+    return ctor(*original)
+
+
+_Size0Sequence = _create_seq_class(0)
+_Size1Sequence = _create_seq_class(1)
+_Size2Sequence = _create_seq_class(2)
+_Size3Sequence = _create_seq_class(3)
+
+_by_size.extend([_Size0Sequence, _Size1Sequence, _Size2Sequence, _Size3Sequence])

opticol-0.1.0a1/opticol/set.py

@@ -0,0 +1,25 @@
+from collections.abc import Set
+from opticol._set import OptimizedSetMeta
+
+
+def _create_set_class(size: int) -> type:
+    return OptimizedSetMeta(f"_Size{size}Set", (Set,), {}, internal_size=size, project=project)
+
+
+_by_size: list[type] = []
+
+
+def project[T](original: Set[T]) -> Set[T]:
+    if len(original) >= len(_by_size):
+        return original
+
+    ctor = _by_size[len(original)]
+    return ctor(*original)
+
+
+_Size0Set = _create_set_class(0)
+_Size1Set = _create_set_class(1)
+_Size2Set = _create_set_class(2)
+_Size3Set = _create_set_class(3)
+
+_by_size.extend([_Size0Set, _Size1Set, _Size2Set, _Size3Set])

opticol-0.1.0a1/opticol.egg-info/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: opticol
+Version: 0.1.0a1
+Summary: Implementations for the various Python Collection ABCs that optimize along various axes.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+## Opticol
+
+Optimized collections (hence *opticol*) for Python. This package provides memory optimized versions of the base Python collection types which are:
+
+* (Mutable)Sequence
+* (Mutable)Mapping
+* (Mutable)Set
+
+The insight behind the package is the following: the size of an empty set is 216 bytes (on Python 3.14) but the size of an empty object with an empty __slots__ member is only 32 bytes. Python programs that hold large datasets in memory could benefit from using these optimized collections which fully implement the respective collection ABCs, but at a fraction of the runtime memory.
+
+So for general users these optimizations will not be worth if if the dataset being used comfortably fits in memory, but applications which currently create tens or hundreds of thousand of Python objects could dramatically lower memory usage without API changes.
+
+## Usage
+
+The optimized classes could be used directly, by creating an EmptySequence directly for example, but the recommended usage is to use the collection level `project` method which tries to project a collection instance into the memory optimized variants automatically. Additionally, there is a factory interface that could be plugged in to allow for different strategies beyond the typical `project` logic.
+
+Consider the following example:
+
+```
+import opticol
+
+optimized_list = opticol.seq_project([]) # Actually an instance of EmptySequence
+optimized_list_single = opticol.mut_seq_project(("MyString",)) # Actually an instance of Small1MutableSequence
+```
+
+A small note that in the current implementation, optimization is only in one direction. That is, if the MutableSequence type is optimized for collections of size 0, 1, 2, 3, then once an operation pushes it past into size 4, further decreasing of the size will not restore the optimization.

opticol-0.1.0a1/opticol.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+README.md
+pyproject.toml
+opticol/__init__.py
+opticol/_mapping.py
+opticol/_sentinel.py
+opticol/_sequence.py
+opticol/_set.py
+opticol/mapping.py
+opticol/mutable_mapping.py
+opticol/mutable_sequence.py
+opticol/mutable_set.py
+opticol/projector.py
+opticol/py.typed
+opticol/sequence.py
+opticol/set.py
+opticol.egg-info/PKG-INFO
+opticol.egg-info/SOURCES.txt
+opticol.egg-info/dependency_links.txt
+opticol.egg-info/top_level.txt

opticol-0.1.0a1/opticol.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

opticol-0.1.0a1/opticol.egg-info/top_level.txt

@@ -0,0 +1 @@
+opticol

opticol-0.1.0a1/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "opticol"
+version = "0.1.0a1"
+description = "Implementations for the various Python Collection ABCs that optimize along various axes."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = []
+
+[tool.black]
+line-length = 100
+target-version = ["py312"]
+preview = true
+
+[tool.uv.sources]
+guppy3 = { git = "https://github.com/zhuyifei1999/guppy3.git", rev = "da86ab98abf20c57b9ead4d653157af8baaa8efd" }
+
+[dependency-groups]
+dev = [
+    "black>=25.12.0",
+    "codespell>=2.4.1",
+    "guppy3",
+    "mypy>=1.19.0",
+    "pylint>=4.0.4",
+]

opticol-0.1.0a1/setup.cfg

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