ramtable 0.3.1__py3-none-any.whl

ramtable/__init__.py

@@ -0,0 +1,15 @@
+"""Public RAMTable API.
+
+Expose :class:`Columns`, :class:`Rows`, and :class:`Table` from the
+``ramtable`` package as a concise, stable import path.
+"""
+
+from .columns import Columns
+from .rows import Rows
+from .table import Table
+
+__all__ = [
+    "Columns",
+    "Rows",
+    "Table",
+]

ramtable/columns.py

@@ -0,0 +1,181 @@
+
+"""Mutable column schema and validation of schema changes."""
+
+from copy import deepcopy
+from typing import Any
+
+from .types import TypeValidator
+
+_MISSING = object()
+
+
+class Columns:
+    """Manage the names and types associated with a table's columns.
+
+    The instance keeps a copy of the supplied schema and shares its owning
+    table's row storage so schema changes remain consistent with existing
+    records.
+    """
+
+    def __init__(
+        self,
+        columns: dict[str, Any],
+        rows_storage: list[dict[str, Any]],
+    ) -> None:
+        """Create a non-empty schema associated with row storage.
+
+        Args:
+            columns: Mapping of column names to supported types.
+            rows_storage: Shared list of table records.
+
+        Raises:
+            ValueError: If the schema is empty or a name is invalid.
+            TypeError: If a type annotation is unsupported.
+        """
+        if not isinstance(columns, dict) or not columns:
+            raise ValueError("Table must have at least one column.")
+
+        self._columns = columns.copy()
+        self._rows_storage = rows_storage
+
+        for name, column_type in self._columns.items():
+            self._validate_name(name)
+            self._validate_type(column_type)
+
+    @staticmethod
+    def _validate_name(name: str) -> None:
+        """Reject column names that are not non-empty strings."""
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError("Column names must be non-empty strings.")
+
+    @staticmethod
+    def _validate_type(column_type: object) -> None:
+        """Reject annotations unsupported by RAMTable's type validator."""
+        if not TypeValidator.is_supported_type(column_type):
+            raise TypeError(
+                f"Unsupported column type: {column_type!r}"
+            )
+
+    def add(
+        self,
+        name: str,
+        column_type: Any,
+        default: Any = _MISSING,
+    ) -> None:
+        """Add a column and initialize existing rows when necessary.
+
+        If records already exist, ``default`` is required. A deep copy of the
+        value is created for each record so mutable defaults are not shared
+        between rows. If there are no rows, an optional default is not stored.
+
+        Raises:
+            ValueError: If the name is empty, already exists, or a required
+                default is missing.
+            TypeError: If the type or default value is invalid.
+        """
+
+        self._validate_name(name)
+        self._validate_type(column_type)
+
+        if name in self._columns:
+            raise ValueError(f"Column '{name}' already exists.")
+
+        if self._rows_storage and default is _MISSING:
+            raise ValueError(
+                "A default value is required when adding a column "
+                "to a table containing rows."
+            )
+
+        if default is not _MISSING:
+            if not TypeValidator.matches_type(default, column_type):
+                raise TypeError(
+                    f"Default value does not match {column_type!r}."
+                )
+
+        # Prepare all default values before changing the table.
+        # This prevents partial updates if copying fails.
+        if self._rows_storage:
+            default_values = [
+                deepcopy(default) for _ in self._rows_storage
+            ]
+
+            for row, value in zip(self._rows_storage, default_values):
+                row[name] = value
+
+        self._columns[name] = column_type
+
+    def remove(self, name: str) -> None:
+        """Remove a column from the schema and all records.
+
+        Raises:
+            ValueError: If the column does not exist or is the last column.
+        """
+
+        if name not in self._columns:
+            raise ValueError(f"Column '{name}' does not exist.")
+
+        if len(self._columns) == 1:
+            raise ValueError(
+                "A table must have at least one column."
+            )
+
+        for row in self._rows_storage:
+            del row[name]
+
+        del self._columns[name]
+
+    def update(self, name: str, new_type: Any) -> None:
+        """Change a column's declared type if all current values match.
+
+        Stored values are not converted. The change is applied only after
+        every record has been validated.
+
+        Raises:
+            ValueError: If the column does not exist.
+            TypeError: If the new type is unsupported or any current value
+                does not match it.
+        """
+
+        if name not in self._columns:
+            raise ValueError(f"Column '{name}' does not exist.")
+
+        self._validate_type(new_type)
+
+        for row in self._rows_storage:
+            value = row[name]
+
+            if not TypeValidator.matches_type(value, new_type):
+                raise TypeError(
+                    f"Existing value in column '{name}' "
+                    f"does not match {new_type!r}."
+                )
+
+        self._columns[name] = new_type
+
+    def get(self, name: str) -> Any:
+        """Return the type annotation of a column.
+
+        Raises:
+            ValueError: If the column does not exist.
+        """
+
+        if name not in self._columns:
+            raise ValueError(f"Column '{name}' does not exist.")
+
+        return self._columns[name]
+
+    def get_all(self) -> dict[str, Any]:
+        """Return a shallow copy of the complete schema."""
+        return self._columns.copy()
+
+    def __contains__(self, name: str) -> bool:
+        """Return whether ``name`` is declared in the schema."""
+        return name in self._columns
+
+    def __len__(self) -> int:
+        """Return the number of declared columns."""
+        return len(self._columns)
+
+    def __repr__(self) -> str:
+        """Return a debugging representation of the schema."""
+        return f"Columns({self._columns!r})"

ramtable/rows.py

@@ -0,0 +1,397 @@
+
+"""Row insertion, retrieval, filtering, update, and removal operations."""
+
+from typing import Any, Callable
+
+from .columns import Columns
+from .types import TypeValidator
+
+_FILTER_OPERATORS: dict[str, Callable[[Any, Any], bool]] = {
+    "==": lambda value, operand: value == operand,
+    "!=": lambda value, operand: value != operand,
+    ">": lambda value, operand: value > operand,
+    ">=": lambda value, operand: value >= operand,
+    "<": lambda value, operand: value < operand,
+    "<=": lambda value, operand: value <= operand,
+    "in": lambda value, operand: value in operand,
+    "not_in": lambda value, operand: value not in operand,
+    "contains": lambda value, operand: operand in value,
+    "startswith": lambda value, operand: value.startswith(operand),
+    "endswith": lambda value, operand: value.endswith(operand),
+}
+
+
+class Rows:
+    """Provide operations on a table's rows.
+
+    Rows are stored as dictionaries in storage shared with :class:`Columns`.
+    Returned copies are shallow: the dictionaries are new, but mutable
+    objects they contain may still be shared.
+    """
+
+    def __init__(
+        self,
+        columns: Columns,
+        storage: list[dict[str, Any]],
+    ) -> None:
+        """Bind the row view to its schema and storage.
+
+        Args:
+            columns: Schema that each row must satisfy.
+            storage: Shared list used to store rows.
+        """
+        self._columns = columns
+        self._storage = storage
+
+    def _validate(self, row: dict[str, Any]) -> None:
+        """Validate that a row has exactly the required columns and types.
+
+        Raises:
+            TypeError: If ``row`` is not a dictionary or a value does not
+                match its declared type.
+            ValueError: If columns are missing or undeclared.
+        """
+        if not isinstance(row, dict):
+            raise TypeError("Row must be a dictionary.")
+
+        schema = self._columns.get_all()
+
+        expected = set(schema)
+        received = set(row)
+
+        if expected != received:
+            missing = expected - received
+            unexpected = received - expected
+
+            raise ValueError(
+                f"Invalid row structure. "
+                f"Missing columns: {missing}. "
+                f"Unexpected columns: {unexpected}."
+            )
+
+        for column, column_type in schema.items():
+            if not TypeValidator.matches_type(
+                row[column], column_type
+            ):
+                raise TypeError(
+                    f"Invalid value for column '{column}'. "
+                    f"Expected {column_type!r}, "
+                    f"received {type(row[column]).__name__}."
+                )
+
+    def _filter(self, where: dict[str, Any]) -> list[dict[str, Any]]:
+        """Return the stored rows that satisfy every condition in ``where``.
+
+        This is the shared engine behind :meth:`filter`, :meth:`delete`, and
+        :meth:`update`. Each key is a column name and each condition is one
+        of:
+
+        * a plain value, matched with ``==``;
+        * a dictionary of operators whose operands must all match;
+        * a callable that receives the cell value and returns a truthy
+          result when the row matches.
+
+        Supported operators are ``==``, ``!=``, ``>``, ``>=``, ``<``,
+        ``<=``, ``in``, ``not_in``, ``contains``, ``startswith``, and
+        ``endswith``. All conditions are combined with ``and``.
+
+        Returned rows are internal references; callers copy them before
+        exposing them outside the class.
+
+        Raises:
+            ValueError: If ``where`` is not a non-empty dictionary, names a
+                column that does not exist, or uses an unknown operator.
+        """
+
+        if not isinstance(where, dict) or not where:
+            raise ValueError(
+                "Filter conditions must be a non-empty dictionary."
+            )
+
+        schema = self._columns.get_all()
+
+        for column, condition in where.items():
+            if column not in schema:
+                raise ValueError(f"Column '{column}' does not exist.")
+
+            if isinstance(condition, dict):
+                if not condition:
+                    raise ValueError(
+                        f"Filter for column '{column}' must not be empty."
+                    )
+
+                for operator in condition:
+                    if operator not in _FILTER_OPERATORS:
+                        raise ValueError(
+                            f"Unknown filter operator {operator!r}. "
+                            "Supported operators: "
+                            f"{', '.join(_FILTER_OPERATORS)}."
+                        )
+
+        def matches(value: Any, condition: Any) -> bool:
+            if isinstance(condition, dict):
+                return all(
+                    _FILTER_OPERATORS[operator](value, operand)
+                    for operator, operand in condition.items()
+                )
+
+            if callable(condition) and not isinstance(condition, type):
+                return bool(condition(value))
+
+            return value == condition
+
+        return [
+            row
+            for row in self._storage
+            if all(
+                matches(row[column], condition)
+                for column, condition in where.items()
+            )
+        ]
+
+    def insert(self, row: dict[str, Any]) -> None:
+        """Validate and append a shallow copy of ``row``.
+
+        Raises:
+            TypeError: If the row or one of its values is invalid.
+            ValueError: If the row does not have exactly the schema columns.
+        """
+
+        self._validate(row)
+        self._storage.append(row.copy())
+
+    def remove(self, row: dict[str, Any]) -> None:
+        """Remove the first row equal to ``row`` after validating its shape.
+
+        Raises:
+            TypeError: If the row or one of its values is invalid.
+            ValueError: If the row does not match the schema or does not exist.
+        """
+
+        self._validate(row)
+
+        try:
+            self._storage.remove(row)
+        except ValueError:
+            raise ValueError(
+                "Row does not exist in this table."
+            ) from None
+
+    def delete(self, where: dict[str, Any]) -> int:
+        """Delete every row that matches ``where``.
+
+        Conditions use the same format as :meth:`filter` and :meth:`update`.
+        To remove one specific row by its full content, use :meth:`remove`.
+
+        Args:
+            where: Non-empty dictionary mapping column names to conditions.
+
+        Returns:
+            Number of deleted rows; may be zero.
+
+        Raises:
+            ValueError: If ``where`` is not a non-empty dictionary, names a
+                column that does not exist, or uses an unknown operator.
+        """
+
+        matches = self._filter(where)
+
+        if matches:
+            matched = {id(row) for row in matches}
+            self._storage[:] = [
+                row for row in self._storage
+                if id(row) not in matched
+            ]
+
+        return len(matches)
+
+    def update(
+        self,
+        where: dict[str, Any],
+        values: dict[str, Any],
+    ) -> int:
+        """Update fields in every row that satisfies ``where``.
+
+        Both ``where`` and ``values`` must be non-empty dictionaries containing
+        existing column names. Conditions use the same flexible format as
+        :meth:`filter`; new values are validated against the schema, but
+        condition values are not. The entire request is validated before any
+        rows are modified.
+
+        Args:
+            where: Conditions that a row must satisfy (see :meth:`filter`).
+            values: Columns and values to assign to each matching row.
+
+        Returns:
+            Number of updated rows; may be zero.
+
+        Raises:
+            TypeError: If an assigned value does not match its column type.
+            ValueError: If either argument is empty or not a dictionary, or
+                if a non-existent column or filter operator is named.
+        """
+
+        if not isinstance(values, dict) or not values:
+            raise ValueError(
+                "Update values must be a non-empty dictionary."
+            )
+
+        schema = self._columns.get_all()
+
+        # Validate update columns and their values.
+        for column, value in values.items():
+            if column not in schema:
+                raise ValueError(
+                    f"Column '{column}' does not exist."
+                )
+
+            if not TypeValidator.matches_type(value, schema[column]):
+                raise TypeError(
+                    f"Invalid value for column '{column}'. "
+                    f"Expected {schema[column]!r}, "
+                    f"received {type(value).__name__}."
+                )
+
+        # Find matching rows before modifying anything. ``_filter`` validates
+        # the conditions and returns references to stored rows.
+        matching_rows = self._filter(where)
+
+        # Apply changes.
+        for row in matching_rows:
+            row.update(values)
+
+        return len(matching_rows)
+
+    def filter(self, where: dict[str, Any]) -> list[dict[str, Any]]:
+        """Return shallow copies of the rows that match ``where``.
+
+        Conditions use the same format as :meth:`update` and :meth:`delete`;
+        see :meth:`_filter` for the supported operators and callables. Rows
+        are returned in storage order.
+
+        Args:
+            where: Non-empty dictionary mapping column names to conditions.
+
+        Returns:
+            New list of shallow row copies; empty when nothing matches.
+
+        Raises:
+            ValueError: If ``where`` is not a non-empty dictionary, names a
+                column that does not exist, or uses an unknown operator.
+        """
+
+        return [row.copy() for row in self._filter(where)]
+
+    def clear(self) -> None:
+        """Remove all rows without changing the schema."""
+        self._storage.clear()
+
+    def get(self, *indices: int) -> list[dict[str, Any]]:
+        """Return all rows or copies of the requested positions.
+
+        With no arguments, return all rows. Indexes support negative values as
+        Python lists do; the requested order is preserved and repeated
+        indexes are allowed.
+
+        Raises:
+            TypeError: If an index is not an integer or is a boolean.
+            IndexError: If an index is out of range.
+        """
+
+        if not indices:
+            return self.get_all()
+
+        selected = []
+
+        for index in indices:
+            if isinstance(index, bool) or not isinstance(index, int):
+                raise TypeError("Row indices must be integers.")
+
+            try:
+                selected.append(self._storage[index].copy())
+            except IndexError:
+                raise IndexError(
+                    f"Row index {index} is out of range."
+                ) from None
+
+        return selected
+
+    def get_one(self, index: int) -> dict[str, Any]:
+        """Return a shallow copy of the row at ``index``.
+
+        Negative indexes are supported. ``bool`` is not accepted as an index,
+        although it is a subclass of ``int`` in Python.
+
+        Raises:
+            TypeError: If the index is not an integer or is a boolean.
+            IndexError: If the index is out of range.
+        """
+
+        if isinstance(index, bool) or not isinstance(index, int):
+            raise TypeError("Row index must be an integer.")
+
+        try:
+            return self._storage[index].copy()
+        except IndexError:
+            raise IndexError(
+                f"Row index {index} is out of range."
+            ) from None
+
+    def get_all(self) -> list[dict[str, Any]]:
+        """Return a new list containing a shallow copy of each row."""
+        return [row.copy() for row in self._storage]
+
+    def get_columns(self, *columns: str) -> dict[str, list[Any]]:
+        """Return value lists for the requested columns.
+
+        If no names are given, include every schema column. The dictionary and
+        lists are new, but their values are not copied.
+
+        Raises:
+            ValueError: If a requested column does not exist.
+        """
+
+        schema = self._columns.get_all()
+
+        if not columns:
+            columns = tuple(schema.keys())
+
+        result = {}
+
+        for column in columns:
+            if column not in schema:
+                raise ValueError(f"Column '{column}' does not exist.")
+
+            result[column] = [
+                row[column] for row in self._storage
+            ]
+
+        return result
+
+    def get_column(self, column: str) -> list[Any]:
+        """Return a new list containing the values of one column.
+
+        Values are not copied.
+
+        Raises:
+            ValueError: If the column does not exist.
+        """
+
+        if column not in self._columns:
+            raise ValueError(f"Column '{column}' does not exist.")
+
+        return [
+            row[column] for row in self._storage
+        ]
+
+    def __len__(self) -> int:
+        """Return the current number of rows."""
+        return len(self._storage)
+
+    def __iter__(self):
+        """Iterate over shallow copies of the current rows."""
+        return iter(self.get_all())
+
+    def __repr__(self) -> str:
+        """Return a short representation with the number of rows."""
+        return f"Rows(count={len(self)})"

ramtable/table.py

@@ -0,0 +1,58 @@
+
+"""Main container coordinating a table's schema and rows."""
+
+from typing import Any
+
+from .columns import Columns
+from .rows import Rows
+
+
+class Table:
+    """Represent an in-memory table with a typed schema and rows.
+
+    The table does not persist data to disk. Its ``columns`` and ``rows``
+    attributes provide operations on the schema and records, respectively.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        columns: dict[str, Any],
+    ) -> None:
+        """Create a table with a non-empty name and schema.
+
+        Args:
+            name: Descriptive table name.
+            columns: Dictionary of column names and supported annotations.
+
+        Raises:
+            ValueError: If the name is not a non-empty string, the schema is
+                empty, or a column name is invalid.
+            TypeError: If a column annotation is unsupported.
+        """
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError("Table name must be a non-empty string.")
+
+        self.name = name
+
+        # Shared internal storage.
+        storage: list[dict[str, Any]] = []
+
+        self.columns = Columns(columns, storage)
+        self.rows = Rows(self.columns, storage)
+
+    def clear(self) -> None:
+        """Remove all records while preserving the column schema."""
+        self.rows.clear()
+
+    def __len__(self) -> int:
+        """Return the current number of rows."""
+        return len(self.rows)
+
+    def __repr__(self) -> str:
+        """Return a representation with the name, columns, and row count."""
+        return (
+            f"Table(name={self.name!r}, "
+            f"columns={list(self.columns.get_all())!r}, "
+            f"rows={len(self.rows)})"
+        )

ramtable/types.py

@@ -0,0 +1,181 @@
+
+"""Recursive validation of type annotations for RAMTable."""
+
+import types as std_types
+from collections import abc
+from typing import Annotated, Any, Literal, Union, get_args, get_origin
+
+
+class TypeValidator:
+    """Check supported annotations and whether values match them.
+
+    Validation is performed at runtime; it does not convert values or
+    implement every static type-checking rule.
+    """
+
+    @classmethod
+    def is_supported_type(cls, value_type: object) -> bool:
+        """Return whether ``value_type`` is an annotation RAMTable can check.
+
+        Supported forms include classes, ``Any``, ``None``, ``Annotated``,
+        unions, ``Literal``, common parameterized collections, fixed or
+        variadic tuples, and ``type[T]``. Other annotation forms return
+        ``False``.
+        """
+        if value_type is Any or value_type is None:
+            return True
+
+        if isinstance(value_type, type):
+            return True
+
+        origin = get_origin(value_type)
+        args = get_args(value_type)
+
+        if origin is Annotated:
+            return bool(args) and cls.is_supported_type(args[0])
+
+        if origin in (Union, std_types.UnionType):
+            return bool(args) and all(
+                cls.is_supported_type(arg) for arg in args
+            )
+
+        if origin is Literal:
+            return bool(args)
+
+        if origin in (list, set, frozenset, abc.Sequence, abc.Set):
+            return not args or (
+                len(args) == 1
+                and cls.is_supported_type(args[0])
+            )
+
+        if origin in (dict, abc.Mapping):
+            return not args or (
+                len(args) == 2
+                and all(cls.is_supported_type(arg) for arg in args)
+            )
+
+        if origin is tuple:
+            if not args:
+                return True
+
+            if len(args) == 2 and args[1] is Ellipsis:
+                return cls.is_supported_type(args[0])
+
+            return all(cls.is_supported_type(arg) for arg in args)
+
+        if origin is type:
+            return (
+                len(args) == 1
+                and isinstance(args[0], type)
+            )
+
+        return False
+
+    @classmethod
+    def matches_type(cls, value: object, value_type: object) -> bool:
+        """Recursively check whether ``value`` matches ``value_type``.
+
+        Simple types follow Python's ``isinstance`` semantics (for example,
+        ``bool`` also matches ``int``). ``Annotated`` checks its base type;
+        ``Literal`` requires equality and an exact type match. Elements and
+        keys in parameterized containers are also checked.
+        """
+        if value_type is Any:
+            return True
+
+        if value_type is None:
+            return value is None
+
+        origin = get_origin(value_type)
+        args = get_args(value_type)
+
+        if origin is Annotated:
+            return cls.matches_type(value, args[0])
+
+        if origin in (Union, std_types.UnionType):
+            return any(
+                cls.matches_type(value, arg) for arg in args
+            )
+
+        if origin is Literal:
+            return any(
+                value == literal and type(value) is type(literal)
+                for literal in args
+            )
+
+        if origin in (list, set, frozenset):
+            if not isinstance(value, origin):
+                return False
+
+            return not args or all(
+                cls.matches_type(item, args[0])
+                for item in value
+            )
+
+        if origin is tuple:
+            if not isinstance(value, tuple):
+                return False
+
+            if not args:
+                return True
+
+            if len(args) == 2 and args[1] is Ellipsis:
+                return all(
+                    cls.matches_type(item, args[0])
+                    for item in value
+                )
+
+            return (
+                len(value) == len(args)
+                and all(
+                    cls.matches_type(item, expected)
+                    for item, expected in zip(value, args)
+                )
+            )
+
+        if origin in (dict, abc.Mapping):
+            if not isinstance(value, origin):
+                return False
+
+            if not args:
+                return True
+
+            key_type, item_type = args
+
+            return all(
+                cls.matches_type(key, key_type)
+                and cls.matches_type(item, item_type)
+                for key, item in value.items()
+            )
+
+        if origin is abc.Sequence:
+            if not isinstance(value, abc.Sequence):
+                return False
+
+            return not args or all(
+                cls.matches_type(item, args[0])
+                for item in value
+            )
+
+        if origin is abc.Set:
+            if not isinstance(value, abc.Set):
+                return False
+
+            return not args or all(
+                cls.matches_type(item, args[0])
+                for item in value
+            )
+
+        if origin is type:
+            if not isinstance(value, type):
+                return False
+
+            try:
+                return issubclass(value, args[0])
+            except TypeError:
+                return False
+
+        try:
+            return isinstance(value, value_type)
+        except TypeError:
+            return False

ramtable-0.3.1.dist-info/METADATA

@@ -0,0 +1,232 @@
+Metadata-Version: 2.5
+Name: ramtable
+Version: 0.3.1
+Summary: A lightweight in-memory table library for Python.
+Author: Thiago Valentín Stilo Limarino
+License-Expression: MIT
+License-File: LICENSE
+Keywords: data-structure,in-memory,python,table
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# RAMTable
+
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+[![PyPI](https://img.shields.io/badge/PyPI-ramtable-blue)](https://pypi.org/project/ramtable/)
+[![TestPyPI](https://img.shields.io/badge/TestPyPI-ramtable-orange)](https://test.pypi.org/project/ramtable/)
+
+RAMTable provides typed in-memory tables for data that only needs to live
+while a program is running. It gives records an explicit schema and common
+operations, without requiring you to manage lists and dictionaries by hand
+or set up a persistent SQL database.
+
+RAMTable is a lightweight Python library with no runtime dependencies. Data
+is kept in memory and is lost when the process ends. RAMTable is not a
+database: it does not execute SQL and does not write data to disk.
+
+## Where it fits
+
+Reach for RAMTable when a plain `list` or `dict` does not provide enough
+structure, but a persistent database is too much:
+
+| | Plain `list` / `dict` | RAMTable | SQL database |
+|---|:---:|:---:|:---:|
+| Schema with declared types | — | ✓ | ✓ |
+| Rows validated on write | — | ✓ | ✓ |
+| Schema changes with data present | manual | ✓ | ✓ |
+| Query language, indexes, constraints | — | — | ✓ |
+| Survives process exit | — | — | ✓ |
+| Setup | none | none | server or files |
+
+Typical scenarios:
+
+- intermediate results of a multi-step process;
+- temporary records staged during a calculation or import;
+- the working set of a long-running task;
+- prototypes that want typed rows before a real database exists.
+
+For simple collections, a list or dictionary is still the right answer. If
+data must survive restarts, be shared between processes, or be queried with
+SQL, use an appropriate persistence solution instead. For analysis and
+vectorized operations, use a data-frame library: RAMTable targets structured
+temporary storage, not analytics.
+
+## Installation
+
+RAMTable requires Python 3.10 or later.
+
+Install the latest stable release from PyPI:
+
+```bash
+python -m pip install ramtable
+```
+
+Pre-releases are published to TestPyPI. To try one:
+
+```bash
+python -m pip install --pre --index-url https://test.pypi.org/simple/ ramtable
+```
+
+TestPyPI is a separate testing index, not the official package index. Stable
+releases are published to PyPI under the name `ramtable`.
+
+Install from a local checkout:
+
+```bash
+python -m pip install .
+```
+
+Install in editable mode for development:
+
+```bash
+python -m pip install --editable .
+```
+
+## Quick start
+
+```python
+from ramtable import Table
+
+people = Table(
+    name="people",
+    columns={
+        "id": int,
+        "name": str,
+        "age": int,
+        "email": str,
+    },
+)
+
+# Every row must contain exactly the columns declared above.
+people.rows.insert(
+    {"id": 1, "name": "Ada", "age": 36, "email": "ada@example.com"}
+)
+people.rows.insert(
+    {"id": 2, "name": "Linus", "age": 28, "email": "linus@example.com"}
+)
+
+print(people.rows.get_column("name"))
+# ['Ada', 'Linus']
+
+# Update every row matching the conditions; returns the number of rows changed.
+updated = people.rows.update(
+    where={"id": 1},
+    values={"name": "Ada Lovelace"},
+)
+print(updated)
+# 1
+
+print(people.rows.get_one(0))
+# {'id': 1, 'name': 'Ada Lovelace', 'age': 36, 'email': 'ada@example.com'}
+
+# Conditions go beyond equality in filter(), update(), and delete().
+older = people.rows.filter({"age": {">": 30}})
+print([row["name"] for row in older])
+# ['Ada Lovelace']
+```
+
+A `Table` exposes two views over the same storage:
+
+- `table.rows`: the data. Insert, read, update, and remove rows.
+- `table.columns`: the schema. Add, remove, and retype columns.
+
+The [user guide](docs/guide.md) walks through every operation step by step.
+
+## Features
+
+- **Explicit schema:** declare column names and types when the table is
+  created.
+- **Runtime validation:** every row must contain exactly the schema's
+  columns, and each value must match its declared type.
+- **Row operations:** insert, retrieve, update, filter, and delete rows.
+- **Flexible conditions:** one condition format powers `filter`, `update`,
+  and `delete`, with comparison, membership, and string operators.
+- **Schema evolution:** add, remove, or retype columns while accounting for
+  existing rows.
+- **Validate-then-write:** update requests are checked in full before any
+  row is modified, so a rejected request never leaves a partial change.
+- **Zero dependencies:** no server, no SQL setup, nothing beyond the package
+  itself.
+
+## Supported types
+
+Besides plain classes, RAMTable understands `Any`, `None`, unions
+(`str | None`), `Annotated`, `Literal`, `type[T]`, and parameterized lists,
+sets, frozensets, sequences, mappings, dictionaries, and tuples. Nested
+arguments are checked recursively:
+
+| Annotation | Example | Rule |
+|---|---|---|
+| Classes | `int`, `str`, `bytes` | `isinstance` |
+| Unions | `str \| None` | any alternative may match |
+| `Literal` | `Literal["pending", "done"]` | value and exact type |
+| Sequence types | `list[str]`, `set[int]`, `Sequence[float]` | container class, then every item |
+| Mapping types | `dict[str, int]`, `Mapping[str, list[int]]` | container class, then every key and value |
+| Tuples | `tuple[int, str]`, `tuple[int, ...]` | fixed positions or one repeated type |
+| `Annotated` | `Annotated[int, "id"]` | base type only; metadata is ignored |
+| Class objects | `type[int]` | subclasses of `T` |
+| `Any` / `None` | — | any value / only `None` |
+
+```python
+from typing import Literal
+from ramtable import Table
+
+events = Table(
+    "events",
+    {
+        "name": str,
+        "status": Literal["pending", "complete"],
+        "tags": list[str],
+    },
+)
+```
+
+Simple classes follow `isinstance` semantics, so a `bool` value also matches
+`int`. `Literal` is stricter: it compares both value and exact type. See
+[types and validation](docs/types-and-validation.md) for the complete rules
+and known limitations.
+
+## Copies and lifecycle
+
+Rows are stored as dictionaries. Inserting a row stores a shallow copy of
+the dictionary; retrieving a row returns a new dictionary containing the same
+values. Mutable objects used as cell values may therefore remain shared
+with the code that supplied or retrieved them.
+
+`table.clear()` removes all rows and preserves the schema. No operation
+writes to disk: records disappear when the process ends.
+
+## Documentation
+
+| Document | Contents |
+|---|---|
+| [User guide](docs/guide.md) | Tables, rows, filtering, schema changes, errors, and limits. |
+| [API reference](docs/api.md) | Every class and method, with arguments, returns, and exceptions. |
+| [Types and validation](docs/types-and-validation.md) | Supported annotations and runtime checking rules. |
+| [Development and releases](docs/development.md) | Project layout, checks, and the release process. |
+| [CHANGELOG](CHANGELOG.md) | Release history. |
+| [LICENSE](LICENSE) | MIT license terms. |
+
+## Project status
+
+The current development version is **0.3.1rc0**. RAMTable is published as
+`ramtable` on both [PyPI](https://pypi.org/project/ramtable/) and
+[TestPyPI](https://test.pypi.org/project/ramtable/). Use PyPI for stable
+releases and TestPyPI to try release candidates and other pre-releases.
+
+The project is at an early stage and will continue to evolve. See the
+[CHANGELOG](CHANGELOG.md) for release history.
+
+## License
+
+RAMTable is distributed under the MIT License. See [LICENSE](LICENSE) for
+the terms.

ramtable-0.3.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+ramtable/__init__.py,sha256=HVrTgXXmZ5jb93ZdGU4jgKx077cjGmDiDUGNQq4Pe38,285
+ramtable/columns.py,sha256=xkHZwX0KuiauJET1ugql8i1LMU5AevclOmLG5ZQA4dU,5805
+ramtable/rows.py,sha256=Jaw4cLI1tppTXZOALBjOKHyIpIk5dfBhTPFg9RoqJVU,13359
+ramtable/table.py,sha256=cshsx6GHY0_MQu2wvupXg3DdiM5lhEdrp0Be7d5MHAc,1731
+ramtable/types.py,sha256=9eB0C7pKA5TkOJdV_VkT3yUO9-D3j8CLnGueeRP-rKA,5290
+ramtable-0.3.1.dist-info/METADATA,sha256=B4kygAq1sZLUhyGgkCqDcO3WZxQUC5gL_t-n8qKgndQ,8120
+ramtable-0.3.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+ramtable-0.3.1.dist-info/licenses/LICENSE,sha256=0o1fe5xZ9sY7cVfXYqFCCRH_25mSui25kyUBbYLvQQ0,1078
+ramtable-0.3.1.dist-info/RECORD,,

ramtable-0.3.1.dist-info/WHEEL

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

ramtable-0.3.1.dist-info/licenses/LICENSE

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