compressed-lists 0.1.0__py3-none-any.whl

compressed_lists/CompressedIntegerList.py

@@ -0,0 +1,92 @@
+from typing import List, Optional, Sequence
+
+import numpy as np
+
+from .CompressedList import CompressedList
+from .partition import Partitioning
+
+__author__ = "Jayaram Kancherla"
+__copyright__ = "Jayaram Kancherla"
+__license__ = "MIT"
+
+
+class CompressedIntegerList(CompressedList):
+    """CompressedList implementation for lists of integers."""
+
+    def __init__(
+        self,
+        unlist_data: np.ndarray,
+        partitioning: Partitioning,
+        element_metadata: dict = None,
+        metadata: dict = None,
+        **kwargs,
+    ):
+        """Initialize a CompressedIntegerList.
+
+        Args:
+            unlist_data:
+                NumPy array of integers.
+
+            partitioning:
+                Partitioning object defining element boundaries.
+
+            element_metadata:
+                Optional metadata for elements.
+
+            metadata:
+                Optional general metadata.
+
+            kwargs:
+                Additional arguments.
+        """
+        super().__init__(
+            unlist_data, partitioning, element_type="integer", element_metadata=element_metadata, metadata=metadata
+        )
+
+    def _extract_range(self, start: int, end: int) -> np.ndarray:
+        """Extract a range from unlist_data.
+
+        Args:
+            start:
+                Start index (inclusive).
+
+            end:
+                End index (exclusive).
+
+        Returns:
+            Same type as unlist_data.
+        """
+        return self._unlist_data[start:end]
+
+    @classmethod
+    def from_list(
+        cls, lst: List[List[int]], names: Optional[Sequence[str]] = None, metadata: dict = None
+    ) -> "CompressedIntegerList":
+        """
+        Create a CompressedIntegerList from a list of integer lists.
+
+        Args:
+            lst:
+                List of integer lists.
+
+            names:
+                Optional names for list elements.
+
+            metadata:
+                Optional metadata.
+
+        Returns:
+            A new CompressedIntegerList.
+        """
+        # Flatten the list
+        flat_data = []
+        for sublist in lst:
+            flat_data.extend(sublist)
+
+        # Create partitioning
+        partitioning = Partitioning.from_list(lst, names)
+
+        # Create unlist_data
+        unlist_data = np.array(flat_data, dtype=np.int64)
+
+        return cls(unlist_data, partitioning, metadata=metadata)

compressed_lists/CompressedList.py

@@ -0,0 +1,583 @@
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Iterator, List, Optional, Sequence, Union
+from warnings import warn
+
+import biocutils as ut
+import numpy as np
+
+from .partition import Partitioning
+
+__author__ = "Jayaram Kancherla"
+__copyright__ = "Jayaram Kancherla"
+__license__ = "MIT"
+
+
+def _validate_data_and_partitions(unlist_data, partition):
+    if len(unlist_data) != partition.nobj():
+        raise ValueError(
+            f"Length of 'unlist_data' ({len(unlist_data)}) "
+            f"doesn't match 'partitioning' total length ({partition.nobj()})."
+        )
+
+
+class CompressedList(ABC):
+    """Base class for compressed list objects.
+
+    `CompressedList` stores list elements concatenated in a single vector-like object
+    with partitioning information that defines where each list element starts and ends.
+    """
+
+    def __init__(
+        self,
+        unlist_data: Any,
+        partitioning: Partitioning,
+        element_type: str = None,
+        element_metadata: dict = None,
+        metadata: Optional[dict] = None,
+        validate: bool = True,
+    ):
+        """Initialize a CompressedList.
+
+        Args:
+            unlist_data:
+                Vector-like object containing concatenated elements.
+
+            partitioning:
+                Partitioning object defining element boundaries.
+
+            element_type:
+                String identifier for the type of elements.
+
+            element_metadata:
+                Optional metadata for elements.
+
+            metadata:
+                Optional general metadata.
+
+            validate:
+                Internal use only.
+        """
+        self._unlist_data = unlist_data
+        self._partitioning = partitioning
+        self._element_type = element_type
+        self._element_metadata = element_metadata or {}
+        self._metadata = metadata or {}
+
+        if validate:
+            _validate_data_and_partitions(self._unlist_data, self._partitioning)
+
+    def _define_output(self, in_place: bool = False) -> "Partitioning":
+        if in_place is True:
+            return self
+        else:
+            return self.__copy__()
+
+    #########################
+    ######>> Copying <<######
+    #########################
+
+    def __deepcopy__(self, memo=None, _nil=[]):
+        """
+        Returns:
+            A deep copy of the current ``Partitioning``.
+        """
+        from copy import deepcopy
+
+        _unlistdata_copy = deepcopy(self._unlist_data)
+        _part_copy = deepcopy(self._partitioning)
+        _elem_type_copy = deepcopy(self._element_type)
+        _elem_metadata_copy = deepcopy(self._element_metadata)
+        _metadata_copy = deepcopy(self._metadata)
+
+        current_class_const = type(self)
+        return current_class_const(
+            unlist_data=_unlistdata_copy,
+            partitioning=_part_copy,
+            element_type=_elem_type_copy,
+            element_metadata=_elem_metadata_copy,
+            metadata=_metadata_copy,
+        )
+
+    def __copy__(self):
+        """
+        Returns:
+            A shallow copy of the current ``Partitioning``.
+        """
+        current_class_const = type(self)
+        return current_class_const(
+            unlist_data=self._unlist_data,
+            partitioning=self._partitioning,
+            element_type=self._element_type,
+            element_metadata=self._element_metadata,
+            metadata=self._metadata,
+        )
+
+    def copy(self):
+        """Alias for :py:meth:`~__copy__`."""
+        return self.__copy__()
+
+    ######################################
+    ######>> length and iterators <<######
+    ######################################
+
+    def __len__(self) -> int:
+        """Return the number of list elements."""
+        return len(self._partitioning)
+
+    def get_element_lengths(self) -> np.ndarray:
+        """Get the lengths of each list element."""
+        return self._partitioning.get_element_lengths()
+
+    def __iter__(self) -> Iterator[Any]:
+        """Iterate over list elements."""
+        for i in range(len(self)):
+            yield self[i]
+
+    ##########################
+    ######>> Printing <<######
+    ##########################
+
+    def __repr__(self) -> str:
+        """
+        Returns:
+            A string representation.
+        """
+        output = f"{type(self).__name__}(number_of_elements={len(self)}"
+        output += ", unlist_data=" + ut.print_truncated_list(self._unlist_data)
+        output += ", partitioning=" + self._partitioning.__repr__()
+        output += ", element_type=" + self._element_type
+
+        if len(self._element_metadata) > 0:
+            output += ", element_metadata=" + ut.print_truncated_dict(self._element_metadata)
+
+        if len(self._metadata) > 0:
+            output += ", metadata=" + ut.print_truncated_dict(self._metadata)
+
+        output += ")"
+        return output
+
+    def __str__(self) -> str:
+        """
+        Returns:
+            A pretty-printed string containing the contents of this object.
+        """
+        output = f"class: {type(self).__name__}\n"
+
+        output += f"number of elements: ({len(self)}) of type: {self._element_type}\n"
+
+        output += f"unlist_data: {ut.print_truncated_list(self._unlist_data)}\n"
+
+        output += f"partitioning: {ut.print_truncated_list(self._partitioning)}\n"
+
+        output += f"element_metadata({str(len(self._element_metadata))}): {ut.print_truncated_list(list(self._element_metadata.keys()), sep=' ', include_brackets=False, transform=lambda y: y)}\n"
+        output += f"metadata({str(len(self._metadata))}): {ut.print_truncated_list(list(self._metadata.keys()), sep=' ', include_brackets=False, transform=lambda y: y)}\n"
+
+        return output
+
+    #############################
+    ######>> element_type <<#####
+    #############################
+
+    def get_element_type(self) -> str:
+        """Return the element_type."""
+        return self._element_type
+
+    @property
+    def element_type(self) -> str:
+        """Alias for :py:attr:`~get_element_type`, provided for back-compatibility."""
+        return self.get_element_type()
+
+    ###########################
+    ######>> partitions <<#####
+    ###########################
+
+    def get_partitioning(self) -> Partitioning:
+        """Return the paritioning info."""
+        return self._partitioning
+
+    @property
+    def paritioning(self) -> Partitioning:
+        """Alias for :py:attr:`~get_paritioning`, provided for back-compatibility."""
+        return self.get_partitioning()
+
+    #######################
+    ######>> names <<######
+    #######################
+
+    def get_names(self) -> Optional[ut.NamedList]:
+        """Get the names of list elements."""
+        return self._partitioning.get_names()
+
+    def set_names(self, names: Sequence[str], in_place: bool = False) -> "CompressedList":
+        """Set the names of list elements.
+
+        names:
+            New names, same as the number of rows.
+
+            May be `None` to remove names.
+
+        in_place:
+            Whether to modify the ``CompressedList`` in place.
+
+        Returns:
+            A modified ``CompressedList`` object, either as a copy of the original
+            or as a reference to the (in-place-modified) original.
+        """
+        output = self._define_output(in_place)
+        output._partitioning = self._partitioning.set_names(names, in_place=False)
+        return output
+
+    @property
+    def names(self) -> Optional[ut.NamedList]:
+        """Alias for :py:attr:`~get_names`."""
+        return self._partitioning.get_names()
+
+    @names.setter
+    def names(self, names: Sequence[str]):
+        """Alias for :py:attr:`~set_names` with ``in_place = True``.
+
+        As this mutates the original object, a warning is raised.
+        """
+        warn(
+            "Setting property 'names' is an in-place operation, use 'set_names' instead",
+            UserWarning,
+        )
+        self.set_names(names=names, in_place=True)
+
+    #############################
+    ######>> unlist_data <<######
+    #############################
+
+    def get_unlist_data(self) -> Any:
+        """Get all elements."""
+        return self._unlist_data
+
+    def set_unlist_data(self, unlist_data: Any, in_place: bool = False) -> "CompressedList":
+        """Set new list elements.
+
+        Args:
+            unlist_data:
+                New vector-like object containing concatenated elements.
+
+            in_place:
+                Whether to modify the ``CompressedList`` in place.
+
+        Returns:
+            A modified ``CompressedList`` object, either as a copy of the original
+            or as a reference to the (in-place-modified) original.
+        """
+        output = self._define_output(in_place)
+
+        _validate_data_and_partitions(unlist_data=unlist_data, partition=self._partitioning)
+
+        output._unlist_data = unlist_data
+        return output
+
+    @property
+    def unlist_data(self) -> Any:
+        """Alias for :py:attr:`~get_unlist_data`."""
+        return self.get_unlist_data()
+
+    @unlist_data.setter
+    def unlist_data(self, unlist_data: Any):
+        """Alias for :py:attr:`~set_unlist_data` with ``in_place = True``.
+
+        As this mutates the original object, a warning is raised.
+        """
+        warn(
+            "Setting property 'unlist_data' is an in-place operation, use 'set_unlist_data' instead",
+            UserWarning,
+        )
+        self.set_unlist_data(unlist_data, in_place=True)
+
+    ###################################
+    ######>> element metadata <<#######
+    ###################################
+
+    def get_element_metadata(self) -> dict:
+        """
+        Returns:
+            Dictionary of metadata for each element in this object.
+        """
+        return self._element_metadata
+
+    def set_element_metadata(self, element_metadata: dict, in_place: bool = False) -> "CompressedList":
+        """Set new element metadata.
+
+        Args:
+            element_metadata:
+                New element metadata for this object.
+
+            in_place:
+                Whether to modify the ``CompressedList`` in place.
+
+        Returns:
+            A modified ``CompressedList`` object, either as a copy of the original
+            or as a reference to the (in-place-modified) original.
+        """
+        if not isinstance(element_metadata, dict):
+            raise TypeError(f"`element_metadata` must be a dictionary, provided {type(element_metadata)}.")
+        output = self._define_output(in_place)
+        output._element_metadata = element_metadata
+        return output
+
+    @property
+    def element_metadata(self) -> dict:
+        """Alias for :py:attr:`~get_element_metadata`."""
+        return self.get_element_metadata()
+
+    @element_metadata.setter
+    def element_metadata(self, element_metadata: dict):
+        """Alias for :py:attr:`~set_element_metadata` with ``in_place = True``.
+
+        As this mutates the original object, a warning is raised.
+        """
+        warn(
+            "Setting property 'element_metadata' is an in-place operation, use 'set_element_metadata' instead",
+            UserWarning,
+        )
+        self.set_element_metadata(element_metadata, in_place=True)
+
+    ###########################
+    ######>> metadata <<#######
+    ###########################
+
+    def get_metadata(self) -> dict:
+        """
+        Returns:
+            Dictionary of metadata for this object.
+        """
+        return self._metadata
+
+    def set_metadata(self, metadata: dict, in_place: bool = False) -> "CompressedList":
+        """Set additional metadata.
+
+        Args:
+            metadata:
+                New metadata for this object.
+
+            in_place:
+                Whether to modify the ``CompressedList`` in place.
+
+        Returns:
+            A modified ``CompressedList`` object, either as a copy of the original
+            or as a reference to the (in-place-modified) original.
+        """
+        if not isinstance(metadata, dict):
+            raise TypeError(f"`metadata` must be a dictionary, provided {type(metadata)}.")
+        output = self._define_output(in_place)
+        output._metadata = metadata
+        return output
+
+    @property
+    def metadata(self) -> dict:
+        """Alias for :py:attr:`~get_metadata`."""
+        return self.get_metadata()
+
+    @metadata.setter
+    def metadata(self, metadata: dict):
+        """Alias for :py:attr:`~set_metadata` with ``in_place = True``.
+
+        As this mutates the original object, a warning is raised.
+        """
+        warn(
+            "Setting property 'metadata' is an in-place operation, use 'set_metadata' instead",
+            UserWarning,
+        )
+        self.set_metadata(metadata, in_place=True)
+
+    ##########################
+    ######>> accessors <<#####
+    ##########################
+
+    def __getitem__(self, key: Union[int, str, slice]) -> Any:
+        """Get an element or slice of elements from the list.
+
+        Args:
+            key:
+                Integer index, string name, or slice.
+
+        Returns:
+            List element(s).
+        """
+        # string keys (names)
+        if isinstance(key, str):
+            if key not in self.names:
+                raise KeyError(f"No element named '{key}'.")
+            key = list(self.names).index(key)
+
+        # integer indices
+        if isinstance(key, int):
+            if key < 0:
+                key += len(self)
+            if key < 0 or key >= len(self):
+                raise IndexError(f"List index '{key}' out of range.")
+
+            start, end = self._partitioning.get_partition_range(key)
+            return self._extract_range(start, end)
+
+        # slices
+        elif isinstance(key, slice):
+            indices = range(*key.indices(len(self)))
+            result = []
+            for i in indices:
+                start, end = self._partitioning.get_partition_range(i)
+                result.append(self._extract_range(start, end))
+
+            # Create a new CompressedList from the result
+            return self.__class__.from_list(
+                result, names=[self.names[i] for i in indices] if self.names[0] is not None else None
+            )
+
+        else:
+            raise TypeError("Index must be int, str, or slice.")
+
+    ##################################
+    ######>> abstract methods <<######
+    ##################################
+
+    @abstractmethod
+    def _extract_range(self, start: int, end: int) -> Any:
+        """Extract a range from `unlist_data`.
+
+        This method must be implemented by subclasses to handle
+        type-specific extraction from `unlist_data`.
+
+        Args:
+            start:
+                Start index (inclusive).
+
+            end:
+                End index (exclusive).
+
+        Returns:
+            Extracted element.
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def from_list(
+        cls, lst: List[Any], names: Optional[Sequence[str]] = None, metadata: dict = None
+    ) -> "CompressedList[Any]":
+        """Create a CompressedList from a regular list.
+
+        This method must be implemented by subclasses to handle
+        type-specific conversion from list to unlist_data.
+
+        Args:
+            lst:
+                List to convert.
+
+            names:
+                Optional names for list elements.
+
+            metadata:
+                Optional metadata.
+
+        Returns:
+            A new `CompressedList`.
+        """
+        pass
+
+    ###########################
+    ######>> coercions <<######
+    ###########################
+
+    def to_list(self) -> List[Any]:
+        """Convert to a regular Python list.
+
+        Returns:
+            A regular Python list with all elements.
+        """
+        return list(self)
+
+    def unlist(self, use_names: bool = True) -> Any:
+        """Get the underlying unlisted data.
+
+        Args:
+            use_names:
+                Whether to include names in the result if applicable.
+
+                Currently not used.
+
+        Returns:
+            The unlisted data.
+        """
+        return self._unlist_data
+
+    def relist(self, unlist_data: Any) -> "CompressedList[Any]":
+        """Create a new `CompressedList` with the same partitioning but different data.
+
+        Args:
+            unlist_data:
+                New unlisted data.
+
+        Returns:
+            A new CompressedList.
+        """
+        _validate_data_and_partitions(unlist_data, self._partitioning)
+
+        return self.__class__(
+            unlist_data,
+            self._partitioning.copy(),
+            element_type=self._element_type,
+            element_metadata=self._element_metadata.copy(),
+            metadata=self._metadata.copy(),
+        )
+
+    def extract_subset(self, indices: Sequence[int]) -> "CompressedList[Any]":
+        """Extract a subset of elements by indices.
+
+        Args:
+            indices:
+                Sequence of indices to extract.
+
+        Returns:
+            A new CompressedList with only the selected elements.
+        """
+        # Validate indices
+        for i in indices:
+            if i < 0 or i >= len(self):
+                raise IndexError(f"Index {i} out of range")
+
+        # Extract element lengths and names
+        new_lengths = [self.get_element_lengths()[i] for i in indices]
+        new_names = [self.names[i] for i in indices] if self.names[0] is not None else None
+
+        # Create new partitioning
+        new_partitioning = Partitioning.from_lengths(new_lengths, new_names)
+
+        # Extract data
+        new_data = []
+        for i in indices:
+            start, end = self._partitioning.get_partition_range(i)
+            if isinstance(self._unlist_data, np.ndarray):
+                new_data.append(self._unlist_data[start:end])
+            else:
+                new_data.extend(self._unlist_data[start:end])
+
+        if isinstance(self._unlist_data, np.ndarray):
+            new_data = np.concatenate(new_data)
+
+        # Create new compressed list
+        return self.__class__(
+            new_data,
+            new_partitioning,
+            element_type=self._element_type,
+            element_metadata={k: v for k, v in self._element_metadata.items() if k in indices},
+            metadata=self._metadata.copy(),
+        )
+
+    def lapply(self, func: Callable) -> "CompressedList[Any]":
+        """Apply a function to each element.
+
+        Args:
+            func:
+                Function to apply to each element.
+
+        Returns:
+            A new CompressedList with the results.
+        """
+        result = [func(elem) for elem in self]
+        return self.__class__.from_list(result, self.names, self._metadata)

compressed_lists/CompressedStringList.py

@@ -0,0 +1,86 @@
+from typing import List, Optional, Sequence
+
+from .CompressedList import CompressedList
+from .partition import Partitioning
+
+__author__ = "Jayaram Kancherla"
+__copyright__ = "Jayaram Kancherla"
+__license__ = "MIT"
+
+
+class CompressedStringList(CompressedList):
+    """CompressedList implementation for lists of strings."""
+
+    def __init__(
+        self,
+        unlist_data: List[str],
+        partitioning: Partitioning,
+        element_metadata: dict = None,
+        metadata: dict = None,
+        **kwargs,
+    ):
+        """Initialize a CompressedStringList.
+
+        Args:
+            unlist_data:
+                List of strings.
+
+            partitioning:
+                Partitioning object defining element boundaries.
+
+            element_metadata:
+                Optional metadata for elements.
+
+            metadata:
+                Optional general metadata.
+
+            kwargs:
+                Additional arguments.
+        """
+        super().__init__(
+            unlist_data, partitioning, element_type="string", element_metadata=element_metadata, metadata=metadata
+        )
+
+    def _extract_range(self, start: int, end: int) -> List[str]:
+        """Extract a range from unlist_data.
+
+        Args:
+            start:
+                Start index (inclusive).
+
+            end:
+                End index (exclusive).
+
+        Returns:
+            List of strings.
+        """
+        return self._unlist_data[start:end]
+
+    @classmethod
+    def from_list(
+        cls, lst: List[List[str]], names: Optional[Sequence[str]] = None, metadata: dict = None
+    ) -> "CompressedStringList":
+        """Create a `CompressedStringList` from a list of string lists.
+
+        Args:
+            lst:
+                List of string lists.
+
+            names:
+                Optional names for list elements.
+
+            metadata:
+                Optional metadata.
+
+        Returns:
+            A new `CompressedStringList`.
+        """
+        # Flatten the list
+        flat_data = []
+        for sublist in lst:
+            flat_data.extend(sublist)
+
+        # Create partitioning
+        partitioning = Partitioning.from_list(lst, names)
+
+        return cls(flat_data, partitioning, metadata=metadata)

compressed_lists/__init__.py

@@ -0,0 +1,21 @@
+import sys
+
+if sys.version_info[:2] >= (3, 8):
+    # TODO: Import directly (no need for conditional) when `python_requires = >= 3.8`
+    from importlib.metadata import PackageNotFoundError, version  # pragma: no cover
+else:
+    from importlib_metadata import PackageNotFoundError, version  # pragma: no cover
+
+try:
+    # Change here if project is renamed and does not equal the package name
+    dist_name = "compressed-lists"
+    __version__ = version(dist_name)
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "unknown"
+finally:
+    del version, PackageNotFoundError
+
+from .partition import Partitioning
+from .CompressedList import CompressedList
+from .CompressedIntegerList import CompressedIntegerList
+from .CompressedStringList import CompressedStringList

compressed_lists/partition.py

@@ -0,0 +1,285 @@
+from typing import List, Optional, Sequence, Union
+from warnings import warn
+
+import biocutils as ut
+import numpy as np
+
+__author__ = "Jayaram Kancherla"
+__copyright__ = "Jayaram Kancherla"
+__license__ = "MIT"
+
+
+def _validate_names(names, expected_len):
+    if names is None:
+        return
+
+    if len(names) != expected_len:
+        raise ValueError("Length of names must match length of ends.")
+
+
+class Partitioning:
+    """Represents partitioning information for a `CompressedList`.
+
+    This is similar to the ``PartitioningByEnd`` class in Bioconductor.
+    It keeps track of where each element begins and ends in the unlisted data.
+    """
+
+    def __init__(self, ends: Sequence[int], names: Optional[Sequence[str]] = None, validate: bool = True):
+        """Initialize a Partitioning object.
+
+        Args:
+            ends:
+                Sequence of ending positions for each partition.
+
+            names:
+                Optional names for each partition.
+
+            validate:
+                Internal use only.
+        """
+        self._ends = np.array(ends, dtype=np.int64)
+
+        # Calculate starts from ends
+        self._starts = np.zeros_like(self._ends)
+        if len(self._ends) > 0:
+            self._starts[1:] = self._ends[:-1]
+
+        self._names = None
+        if names is not None:
+            self._names = ut.NamedList(names)
+
+        if validate:
+            _validate_names(names, len(ends))
+
+    @classmethod
+    def from_lengths(cls, lengths: Sequence[int], names: Optional[Sequence[str]] = None) -> "Partitioning":
+        """Create a Partitioning from a sequence of lengths.
+
+        Args:
+            lengths:
+                Sequence of partition lengths.
+
+            names:
+                Optional names for each partition.
+
+        Returns:
+            A new Partitioning object.
+        """
+        ends = np.cumsum(lengths)
+        return cls(ends, names)
+
+    @classmethod
+    def from_list(cls, lst: List, names: Optional[Sequence[str]] = None) -> "Partitioning":
+        """Create a Partitioning from a list by using the lengths of each element.
+
+        Args:
+            lst:
+                A list to create partitioning from.
+
+            names:
+                Optional names for each partition.
+
+        Returns:
+            A new Partitioning object.
+        """
+        lengths = [len(item) if hasattr(item, "__len__") else 1 for item in lst]
+        return cls.from_lengths(lengths, names)
+
+    def _define_output(self, in_place: bool = False) -> "Partitioning":
+        if in_place is True:
+            return self
+        else:
+            return self.__copy__()
+
+    #########################
+    ######>> Copying <<######
+    #########################
+
+    def __deepcopy__(self, memo=None, _nil=[]):
+        """
+        Returns:
+            A deep copy of the current ``Partitioning``.
+        """
+        from copy import deepcopy
+
+        _ends_copy = deepcopy(self._ends)
+        _names_copy = deepcopy(self._names)
+
+        current_class_const = type(self)
+        return current_class_const(
+            ends=_ends_copy,
+            names=_names_copy,
+        )
+
+    def __copy__(self):
+        """
+        Returns:
+            A shallow copy of the current ``Partitioning``.
+        """
+        current_class_const = type(self)
+        return current_class_const(
+            ends=self._ends,
+            names=self._names,
+        )
+
+    def copy(self):
+        """Alias for :py:meth:`~__copy__`."""
+        return self.__copy__()
+
+    ######################################
+    ######>> length and iterators <<######
+    ######################################
+
+    def __len__(self) -> int:
+        """Return the number of partitions."""
+        return len(self._ends)
+
+    def get_nobj(self) -> int:
+        """Return the total number of objects across all partitions."""
+        return self._ends[-1] if len(self._ends) > 0 else 0
+
+    def nobj(self) -> int:
+        """Alias for :py:attr:`~get_nobj`."""
+        return self.get_nobj()
+
+    def get_element_lengths(self) -> np.ndarray:
+        """Return the lengths of each partition."""
+        return self._ends - self._starts
+
+    def element_lengths(self) -> int:
+        """Alias for :py:attr:`~get_element_lengths`."""
+        return self.get_element_lengths()
+
+    ##########################
+    ######>> Printing <<######
+    ##########################
+
+    def __repr__(self) -> str:
+        """
+        Returns:
+            A string representation.
+        """
+        output = f"{type(self).__name__}(number_of_elements={len(self)}"
+
+        if self._names is not None:
+            output += ", names=" + ut.print_truncated_list(self._names)
+
+        output += ")"
+        return output
+
+    def __str__(self) -> str:
+        """
+        Returns:
+            A pretty-printed string containing the contents of this object.
+        """
+        output = f"class: {type(self).__name__}\n"
+
+        output += f"num of elements: ({len(self)})\n"
+
+        output += f"names({0 if self._names is None else len(self._names)}): {' ' if self._names is None else ut.print_truncated_list(self._names)}\n"
+
+        return output
+
+    ##########################
+    ######>> accessors <<#####
+    ##########################
+
+    def get_partition_range(self, i: int) -> tuple:
+        """Get the start and end indices for partition ``i``."""
+        if i < 0 or i >= len(self):
+            raise IndexError(f"Partition index {i} out of range.")
+        return (self._starts[i], self._ends[i])
+
+    def __getitem__(self, key: Union[int, slice]) -> Union[tuple, List[tuple]]:
+        """Get partition range(s) by index or slice.
+
+        Args:
+            key:
+                Integer index or slice.
+
+        Returns:
+            Tuple of (start, end) or list of such tuples.
+        """
+        if isinstance(key, int):
+            return self.get_partition_range(key)
+        elif isinstance(key, slice):
+            indices = range(*key.indices(len(self)))
+            return [self.get_partition_range(i) for i in indices]
+        else:
+            raise TypeError("Index must be 'int' or 'slice'.")
+
+    ######################
+    ######>> names <<#####
+    ######################
+
+    def get_names(self) -> Optional[ut.NamedList]:
+        """Return the names of each partition."""
+        return self._names
+
+    def set_names(self, names: Optional[List[str]], in_place: bool = False) -> "Partitioning":
+        """Set the names of list elements.
+
+        Args:
+            names:
+                New names, same as the number of elements.
+
+                May be `None` to remove row names.
+
+            in_place:
+                Whether to modify the ``Partitioning`` in place.
+
+        Returns:
+            A modified ``Partitioning`` object, either as a copy of the original
+            or as a reference to the (in-place-modified) original.
+        """
+        if names is not None and not isinstance(names, ut.Names):
+            names = ut.Names(names)
+
+        _validate_names(names, len(self._ends))
+
+        output = self._define_output(in_place)
+        output._names = names
+        return output
+
+    @property
+    def names(self) -> Optional[ut.Names]:
+        """Alias for :py:attr:`~get_names`, provided for back-compatibility."""
+        return self.get_names()
+
+    @names.setter
+    def names(self, names: Optional[List[str]]):
+        """Alias for :py:meth:`~set_names` with ``in_place = True``.
+
+        As this mutates the original object, a warning is raised.
+        """
+        warn(
+            "Setting property 'row_names' is an in-place operation, use 'set_names' instead",
+            UserWarning,
+        )
+        self.set_names(names, in_place=True)
+
+    #####################
+    ######>> ends <<#####
+    #####################
+
+    def get_ends(self) -> Optional[ut.NamedList]:
+        """Return the names of each partition."""
+        return self._ends
+
+    @property
+    def ends(self) -> Optional[ut.Names]:
+        """Alias for :py:attr:`~get_ends`, provided for back-compatibility."""
+        return self.get_ends()
+    
+    #######################
+    ######>> starts <<#####
+    #######################
+
+    def get_starts(self) -> Optional[ut.NamedList]:
+        """Return the starts of each partition."""
+        return self._starts
+
+    @property
+    def starts(self) -> Optional[ut.Names]:
+        """Alias for :py:attr:`~get_starts`, provided for back-compatibility."""
+        return self.get_starts()

compressed_lists-0.1.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: compressed-lists
+Version: 0.1.0
+Summary: Memory-efficient container for list-like objects
+Home-page: https://github.com/biocpy/compressed-lists
+Author: Jayaram Kancherla
+Author-email: jayaram.kancherla@gmail.com
+License: MIT
+Project-URL: Documentation, https://github.com/biocpy/compressed-lists
+Platform: any
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+License-File: LICENSE.txt
+Requires-Dist: importlib-metadata; python_version < "3.8"
+Requires-Dist: biocutils
+Provides-Extra: testing
+Requires-Dist: setuptools; extra == "testing"
+Requires-Dist: pytest; extra == "testing"
+Requires-Dist: pytest-cov; extra == "testing"
+Dynamic: license-file
+
+[![PyPI-Server](https://img.shields.io/pypi/v/compressed-lists.svg)](https://pypi.org/project/compressed-lists/)
+![Unit tests](https://github.com/BiocPy/compressed-lists/actions/workflows/run-tests.yml/badge.svg)
+
+# CompressedList Implementation in Python
+
+A Python implementation of the `CompressedList` class from R/Bioconductor for memory-efficient list-like objects.
+
+`CompressedList` is a memory-efficient container for list-like objects. Instead of storing each list element separately, it concatenates all elements into a single vector-like object and maintains information about where each original element begins and ends. This approach is significantly more memory-efficient than standard lists, especially when dealing with many list elements.
+
+## Install
+
+To get started, install the package from [PyPI](https://pypi.org/project/compressed-lists/)
+
+```bash
+pip install compressed-lists
+```
+
+## Usage
+
+
+```py
+from compressed_lists import CompressedIntegerList, CompressedStringList
+
+# Create a CompressedIntegerList
+int_data = [[1, 2, 3], [4, 5], [6, 7, 8, 9]]
+names = ["A", "B", "C"]
+int_list = CompressedIntegerList.from_list(int_data, names)
+
+# Access elements
+print(int_list[0])      # [1, 2, 3]
+print(int_list["B"])    # [4, 5]
+print(int_list[1:3])    # Slice of elements
+
+# Apply a function to each element
+squared = int_list.lapply(lambda x: [i**2 for i in x])
+print(squared[0])       # [1, 4, 9]
+
+# Convert to a regular Python list
+regular_list = int_list.to_list()
+
+# Create a CompressedStringList
+char_data = [["apple", "banana"], ["cherry", "date", "elderberry"], ["fig"]]
+char_list = CompressedStringList.from_list(char_data)
+```
+
+### Partitioning
+
+The `Partitioning` class handles the information about where each element begins and ends in the concatenated data. It allows for efficient extraction of elements without storing each element separately.
+
+```python
+from compressed_lists import Partitioning
+
+# Create partitioning from end positions
+ends = [3, 5, 10]
+names = ["A", "B", "C"]
+part = Partitioning(ends, names)
+
+# Get partition range for an element
+start, end = part[1]  # Returns (3, 5)
+```
+
+> [!NOTE]
+>
+> Check out the [documentation](https://biocpy.github.io/compressed-lists) for extending CompressedLists to custom data types.
+
+<!-- biocsetup-notes -->
+
+## Note
+
+This project has been set up using [BiocSetup](https://github.com/biocpy/biocsetup)
+and [PyScaffold](https://pyscaffold.org/).

compressed_lists-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+compressed_lists/CompressedIntegerList.py,sha256=B4Eq3DgNeRbAL9Qpw3QQtwglMX4CT24dMSxGaIO12KE,2362
+compressed_lists/CompressedList.py,sha256=7lIXMwW-451SgDMJ8pyMKi7kh1bjWDJb7n46ZkYQ8_c,18585
+compressed_lists/CompressedStringList.py,sha256=pnz5C9WSeSkn9JgTclgYpf2ngUoaEfqw3lltf2LVMU0,2219
+compressed_lists/__init__.py,sha256=u1mmk8IyiPBrzcT5j-78aQDsLW6Ssk73UrHysT1cLNg,779
+compressed_lists/partition.py,sha256=tUeQY5CP3nb3n-iWMd5a4cJftxB3n7ptGKjmty0vbpM,8478
+compressed_lists-0.1.0.dist-info/licenses/LICENSE.txt,sha256=qI2hRZobcUlj8gqFqXwqt522HeYyWvHLF00zCSZofHA,1084
+compressed_lists-0.1.0.dist-info/METADATA,sha256=V5uNObHECSupJ_QumenbqO3BgbVXjh9hl2_HYYP7E28,3235
+compressed_lists-0.1.0.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+compressed_lists-0.1.0.dist-info/top_level.txt,sha256=F89a770vqkz9CN7_voSVePD3jhhCwTQ51KalyJO4xpQ,17
+compressed_lists-0.1.0.dist-info/RECORD,,

compressed_lists-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (78.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

compressed_lists-0.1.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Jayaram Kancherla
+
+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.

compressed_lists-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+compressed_lists