diff --git a/docs/src/lib/content/project.ts b/docs/src/lib/content/project.ts index 121b7e0..4a745bb 100644 --- a/docs/src/lib/content/project.ts +++ b/docs/src/lib/content/project.ts @@ -38,7 +38,7 @@ export const project = parseProject({ "meta": { "searchCategory": "module", "name": "column", - "source": "\"\"\"\nThe module containing the logic for SQLiteFrame columns.\n\"\"\"\n\nfrom __future__ import annotations\nfrom dataclasses import dataclass, field\nfrom ..types import Type\nfrom ..where import Comparisons, Condition\nfrom ..foreign_key import ForeignKey\nif False:\n from .entity import Entity\n\n\n@dataclass(frozen=True, slots=True)\nclass Column:\n \"\"\"\n The implementation for SQLiteFrame columns.\n \"\"\"\n\n table: Entity = field(repr=False)\n name: str\n type: Type | ForeignKey\n\n @property\n def is_primary_key(self) -> bool:\n \"\"\"\n Determines whether this column is a primary key column.\n\n :return: Whether this column is a primary key column\n \"\"\"\n return self.type.primary_key\n\n @property\n def is_nullable(self) -> bool:\n \"\"\"\n Determines whether this column is nullable.\n\n :return: Whether this column is nullable\n \"\"\"\n return self.type.nullable\n\n @property\n def is_foreign_key(self) -> bool:\n \"\"\"\n Determines whether this column is a foreign key column.\n\n :return: Whether this column is a foreign key column\n \"\"\"\n return isinstance(self.type, ForeignKey)\n\n @property\n def default(self) -> object | None:\n \"\"\"\n Gets the default value of this column - None is returned if no default exists.\n\n :return: The default value of this column\n \"\"\"\n return self.type.default\n\n def __str__(self) -> str:\n \"\"\"\n The string representation for this column, used when it is being executed.\n\n :return: The valid SQL string representing this column\n \"\"\"\n\n primary_key = \" PRIMARY KEY\" if self.is_primary_key else \"\"\n not_null = \"\" if self.is_nullable else \" NOT NULL\"\n default = \"\" if self.default is None else f\" DEFAULT {self.type.encode(self.default)}\"\n if self.is_foreign_key:\n return str(self.type)\n return f\"{self.type.sql_name()}{primary_key}{not_null}{default}\"\n\n def __eq__(self, other: object) -> Condition:\n \"\"\"\n Column == Other\n\n :param other: The right-side item to generate a Condition object from\n :return: The Condition object representing this condition\n \"\"\"\n return Condition(self, Comparisons.EQUAL, other)\n\n def __ne__(self, other: object, **kwargs) -> Condition:\n \"\"\"\n Column != Other\n\n :param other: The right-side item to generate a Condition object from\n :return: The Condition object representing this condition\n \"\"\"\n return Condition(self, Comparisons.NOT_EQUAL, other)\n\n def __gt__(self, other: object) -> Condition:\n \"\"\"\n Column > Other\n\n :param other: The right-side item to generate a Condition object from\n :return: The Condition object representing this condition\n \"\"\"\n return Condition(self, Comparisons.GREATER, other)\n\n def __ge__(self, other: object) -> Condition:\n \"\"\"\n Column >= Other\n\n :param other: The right-side item to generate a Condition object from\n :return: The Condition object representing this condition\n \"\"\"\n return Condition(self, Comparisons.GREATER_EQUAL, other)\n\n def __lt__(self, other: object) -> Condition:\n \"\"\"\n Column < Other\n\n :param other: The right-side item to generate a Condition object from\n :return: The Condition object representing this condition\n \"\"\"\n return Condition(self, Comparisons.LESS, other)\n\n def __le__(self, other: object) -> Condition:\n \"\"\"\n Column <= Other\n\n :param other: The right-side item to generate a Condition object from\n :return: The Condition object representing this condition\n \"\"\"\n return Condition(self, Comparisons.LESS_EQUAL, other)\n\n def __neg__(self) -> Condition:\n \"\"\"\n -Column\n\n Checks whether this column is false.\n\n :return: The Condition object representing this condition\n \"\"\"\n if not issubclass(self.type.decoded_type, bool):\n raise TypeError(\"Cannot run __bool__ on non-boolean column\")\n return Condition(self, Comparisons.EQUAL, 0)\n\n def __pos__(self) -> Condition:\n \"\"\"\n +Column\n\n Checks whether this column is true.\n\n :return: The Condition object representing this condition\n \"\"\"\n if not issubclass(self.type.decoded_type, bool):\n raise TypeError(\"Cannot run __bool__ on non-boolean column\")\n return Condition(self, Comparisons.EQUAL, 1)\n", + "source": "\"\"\"\nThe module containing the logic for SQLiteFrame columns.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import TYPE_CHECKING\nfrom dataclasses import dataclass, field\nfrom ..types import Type\nfrom ..where import Comparisons, Condition\nfrom ..foreign_key import ForeignKey\nif TYPE_CHECKING:\n from .entity import Entity\n\n\n@dataclass(frozen=True, slots=True)\nclass Column:\n \"\"\"\n The implementation for SQLiteFrame columns.\n \"\"\"\n\n table: Entity = field(repr=False)\n name: str\n type: Type | ForeignKey\n\n @property\n def is_primary_key(self) -> bool:\n \"\"\"\n Determines whether this column is a primary key column.\n\n :return: Whether this column is a primary key column\n \"\"\"\n return self.type.primary_key\n\n @property\n def is_nullable(self) -> bool:\n \"\"\"\n Determines whether this column is nullable.\n\n :return: Whether this column is nullable\n \"\"\"\n return self.type.nullable\n\n @property\n def is_foreign_key(self) -> bool:\n \"\"\"\n Determines whether this column is a foreign key column.\n\n :return: Whether this column is a foreign key column\n \"\"\"\n return isinstance(self.type, ForeignKey)\n\n @property\n def default(self) -> object | None:\n \"\"\"\n Gets the default value of this column - None is returned if no default exists.\n\n :return: The default value of this column\n \"\"\"\n return self.type.default\n\n def __str__(self) -> str:\n \"\"\"\n The string representation for this column, used when it is being executed.\n\n :return: The valid SQL string representing this column\n \"\"\"\n\n primary_key = \" PRIMARY KEY\" if self.is_primary_key else \"\"\n not_null = \"\" if self.is_nullable else \" NOT NULL\"\n default = \"\" if self.default is None else f\" DEFAULT {self.type.encode(self.default)}\"\n if self.is_foreign_key:\n return str(self.type)\n return f\"{self.type.sql_name()}{primary_key}{not_null}{default}\"\n\n def __eq__(self, other: object) -> Condition:\n \"\"\"\n Column == Other\n\n :param other: The right-side item to generate a Condition object from\n :return: The Condition object representing this condition\n \"\"\"\n return Condition(self, Comparisons.EQUAL, other)\n\n def __ne__(self, other: object, **kwargs) -> Condition:\n \"\"\"\n Column != Other\n\n :param other: The right-side item to generate a Condition object from\n :return: The Condition object representing this condition\n \"\"\"\n return Condition(self, Comparisons.NOT_EQUAL, other)\n\n def __gt__(self, other: object) -> Condition:\n \"\"\"\n Column > Other\n\n :param other: The right-side item to generate a Condition object from\n :return: The Condition object representing this condition\n \"\"\"\n return Condition(self, Comparisons.GREATER, other)\n\n def __ge__(self, other: object) -> Condition:\n \"\"\"\n Column >= Other\n\n :param other: The right-side item to generate a Condition object from\n :return: The Condition object representing this condition\n \"\"\"\n return Condition(self, Comparisons.GREATER_EQUAL, other)\n\n def __lt__(self, other: object) -> Condition:\n \"\"\"\n Column < Other\n\n :param other: The right-side item to generate a Condition object from\n :return: The Condition object representing this condition\n \"\"\"\n return Condition(self, Comparisons.LESS, other)\n\n def __le__(self, other: object) -> Condition:\n \"\"\"\n Column <= Other\n\n :param other: The right-side item to generate a Condition object from\n :return: The Condition object representing this condition\n \"\"\"\n return Condition(self, Comparisons.LESS_EQUAL, other)\n\n def __neg__(self) -> Condition:\n \"\"\"\n -Column\n\n Checks whether this column is false.\n\n :return: The Condition object representing this condition\n \"\"\"\n if not issubclass(self.type.decoded_type, bool):\n raise TypeError(\"Cannot run __bool__ on non-boolean column\")\n return Condition(self, Comparisons.EQUAL, 0)\n\n def __pos__(self) -> Condition:\n \"\"\"\n +Column\n\n Checks whether this column is true.\n\n :return: The Condition object representing this condition\n \"\"\"\n if not issubclass(self.type.decoded_type, bool):\n raise TypeError(\"Cannot run __bool__ on non-boolean column\")\n return Condition(self, Comparisons.EQUAL, 1)\n", "shortDescription": "The module containing the logic for SQLiteFrame columns.", "longDescription": null, "deprecations": [], @@ -126,7 +126,7 @@ export const project = parseProject({ "meta": { "searchCategory": "module", "name": "entity", - "source": "\"\"\"\nThe module containing the logic for entities (tables) in SQLiteFrame\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import TypeVar, Literal, Iterable, Optional, Callable, Iterator\nfrom pprint import pformat\nfrom inspect import getmembers, isroutine\nfrom .column import Column\nfrom ..types import Type\nfrom ..statements import InsertInto, Set, CreateTable, Select, DeleteFrom, DropTable\nfrom ..wildcards import Wildcards\nfrom ..foreign_key import ForeignKey\nif False:\n from ..database import Database\n\n\nTableT = TypeVar(\"TableT\")\nColumnT = TypeVar(\"ColumnT\", bound=Column)\n\n\ndef table(database: Database, auto_create: bool = True) -> Callable[[type[TableT]], Entity | TableT]:\n \"\"\"\n The decorator used to declare a table in a schema.\n\n :param database: The database the table belongs to\n :param auto_create: Whether the table should be created in the database automatically, after it is declared\n :return: A wrapper function to convert a valid class into an Entity\n \"\"\"\n\n def wrapper(table_: type[TableT]) -> Entity | type[TableT]:\n \"\"\"\n The wrapper method in the decorator, which returns an Entity from a valid class.\n\n :param table_: The class to convert\n :return: An entity object with all the declared data\n \"\"\"\n\n return Entity(table_, database, auto_create=auto_create)\n return wrapper\n\n\nclass Entity:\n \"\"\"\n The class containing the logic for Entities in SQLiteFrame.\n \"\"\"\n\n def __init__(self, table_: Type[TableT], database: Database, auto_create: bool = True):\n \"\"\"\n :param table_: The decorated table class\n :param database: The database the table belongs to\n :param auto_create: Whether the table should be created in the database automatically, after it is declared\n \"\"\"\n self.database = database\n self.auto_create = auto_create\n self.table_name = None\n self.columns = []\n self.integrate_with_structure(table_)\n\n def integrate_with_structure(self, table_: Type[TableT]) -> None:\n \"\"\"\n Creates and registers the table with the database as necessary and declared.\n\n :param table_: The decorated table class\n \"\"\"\n\n self.database.add_table(self)\n self.table_name = table_.__name__\n for column in self.extract_columns(table_):\n if hasattr(self, column.name):\n raise NameError(f\"Column name '{column.name}' cannot exist within a table\") from None\n setattr(self, column.name, column)\n self.columns.append(column)\n if self.auto_create:\n with self.database.connection():\n try:\n self.create_table().execute()\n except NameError:\n raise ValueError(\"Cannot lazy-load foreign key with auto_create=True\") from None\n\n def __repr__(self) -> str:\n \"\"\"\n An internal string representation of the table.\n\n :return: The columns of this table formatted as a string\n \"\"\"\n return pformat(self.columns)\n\n def __str__(self) -> str:\n \"\"\"\n A string representation of the table.\n\n :return: The name of the table\n \"\"\"\n return self.table_name\n\n def extract_columns(self, table_: Type[TableT]) -> Iterator[Column]:\n \"\"\"\n Extracts the declared columns from a valid class definition of a class in the schema.\n\n :param table_: The decorated table class\n :return: A generator which iterates each of the created Column objects\n \"\"\"\n\n column_information = list(filter(lambda member: not member[0].startswith(\"__\"),\n getmembers(table_, lambda member: not isroutine(member))))\n for name, column in column_information:\n yield self.amend_column(name, column)\n\n def amend_column(self, column_name: str, column_type: Type | type | ForeignKey) -> Column:\n \"\"\"\n Converts a column as defined in the schema into a valid Column object.\n\n :param column_name: The defined name of the column\n :param column_type: The defined type of the column\n :return: The valid column object to be used by SQLiteFrame\n \"\"\"\n if isinstance(column_type, type): # Plain Key\n column_type = column_type()\n return Column(self, column_name, column_type)\n\n def sort_columns(self, columns: Iterable[Column | Wildcards],\n base_columns_override: Optional[list[Column]] = None) -> list[Column]:\n \"\"\"\n Returns the given columns in the correct order as per the schema.\n\n This is used in SELECT statements to ensure that the column order\n matches with the order of columns in the returned data.\n\n :param columns: The columns to sort\n :param base_columns_override: An override mechanism for the columns to base the ordering off of\n :return: The sorted list of columns\n \"\"\"\n base_columns = self.columns if base_columns_override is None else base_columns_override\n if Wildcards.All in columns:\n return base_columns\n return sorted(columns, key=lambda column: base_columns.index(column))\n\n def set(self, data: dict[ColumnT, ColumnT.type.decoded_type]) -> Set:\n \"\"\"\n Create a SET statement which runs on this table.\n\n :param data: The data to set into this table as a valid mapping\n :return: A Set statement object, which can be operated on further.\n \"\"\"\n\n for column in data:\n if not column.is_nullable and data[column] is None:\n raise ValueError(f\"Non-nullable column '{column.name}' passed NULL\") from None\n return Set(self, data)\n\n def insert_into(self, data: dict[ColumnT, ColumnT.type.decoded_type]) -> InsertInto:\n \"\"\"\n Create an INSERT INTO statement which runs on this table.\n\n :param data: The data to set into this table as a valid mapping\n :return: An InsertInto statement object, which can be operated on further.\n \"\"\"\n\n for column in data:\n if not column.is_nullable and data[column] is None:\n raise ValueError(f\"Non-nullable column '{column.name}' passed NULL\") from None\n for column in set(self.columns) - set(data):\n if not column.is_nullable and column.default is None:\n raise ValueError(f\"Non-nullable column '{column.name}' passed NULL\") from None\n data[column] = None\n return InsertInto(self, data)\n\n def select(self, *columns: Column | Literal[Wildcards.All], distinct: bool = False) -> Select:\n \"\"\"\n Create an SELECT statement which runs on this table.\n\n :param columns: The column(s) to select\n :param distinct: Whether to select only distinct (non-duplicate) data\n :return: A Select statement object, which can be operated on further.\n \"\"\"\n\n if Wildcards.All in columns:\n columns = [Wildcards.All]\n return Select(self, list(columns), distinct=distinct)\n\n def delete_from(self) -> DeleteFrom:\n \"\"\"\n Create an DELETE FROM statement which runs on this table.\n\n :return: A DeleteFrom statement object, which can be operated on further.\n \"\"\"\n\n return DeleteFrom(self)\n\n def drop_table(self) -> DropTable:\n \"\"\"\n Create an DROP TABLE statement which runs on this table.\n\n :return: A DropTable statement object, which can be operated on further.\n \"\"\"\n\n return DropTable(self)\n\n def __getitem__(self, item: ColumnT.type.decoded_type) -> ColumnT.type.decoded_type:\n \"\"\"\n Entity[data] --> data\n\n This is method which serves only to create a more declarative API - it can be used when inserting\n or setting data into a foreign key column, to explicitly show which table the data being input\n is intended to be coming from.\n\n :param item: The data in the primary key column of this table\n :return: The same data input as a parameter\n \"\"\"\n\n return item\n\n def create_table(self) -> CreateTable:\n \"\"\"\n Create an CREATE TABLE statement which runs on this table.\n\n :return: A CreateTable statement object, which can be operated on further.\n \"\"\"\n return CreateTable(self, self.columns)\n", + "source": "\"\"\"\nThe module containing the logic for entities (tables) in SQLiteFrame\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import TypeVar, Literal, Iterable, Optional, Callable, Iterator, TYPE_CHECKING\nfrom pprint import pformat\nfrom inspect import getmembers, isroutine\nfrom .column import Column\nfrom ..types import Type\nfrom ..statements import InsertInto, Set, CreateTable, Select, DeleteFrom, DropTable\nfrom ..wildcards import Wildcards\nfrom ..foreign_key import ForeignKey\nif TYPE_CHECKING:\n from ..database import Database\n\n\nTableT = TypeVar(\"TableT\")\nColumnT = TypeVar(\"ColumnT\", bound=Column)\n\n\ndef table(database: Database, auto_create: bool = True) -> Callable[[type[TableT]], Entity | TableT]:\n \"\"\"\n The decorator used to declare a table in a schema.\n\n :param database: The database the table belongs to\n :param auto_create: Whether the table should be created in the database automatically, after it is declared\n :return: A wrapper function to convert a valid class into an Entity\n \"\"\"\n\n def wrapper(table_: type[TableT]) -> Entity | type[TableT]:\n \"\"\"\n The wrapper method in the decorator, which returns an Entity from a valid class.\n\n :param table_: The class to convert\n :return: An entity object with all the declared data\n \"\"\"\n\n return Entity(table_, database, auto_create=auto_create)\n return wrapper\n\n\nclass Entity:\n \"\"\"\n The class containing the logic for Entities in SQLiteFrame.\n \"\"\"\n\n def __init__(self, table_: Type[TableT], database: Database, auto_create: bool = True):\n \"\"\"\n :param table_: The decorated table class\n :param database: The database the table belongs to\n :param auto_create: Whether the table should be created in the database automatically, after it is declared\n \"\"\"\n self.database = database\n self.auto_create = auto_create\n self.table_name = None\n self.columns = []\n self.integrate_with_structure(table_)\n\n def integrate_with_structure(self, table_: Type[TableT]) -> None:\n \"\"\"\n Creates and registers the table with the database as necessary and declared.\n\n :param table_: The decorated table class\n \"\"\"\n\n self.database.add_table(self)\n self.table_name = table_.__name__\n for column in self.extract_columns(table_):\n if hasattr(self, column.name):\n raise NameError(f\"Column name '{column.name}' cannot exist within a table\") from None\n setattr(self, column.name, column)\n self.columns.append(column)\n if self.auto_create:\n with self.database.connection():\n try:\n self.create_table().execute()\n except NameError:\n raise ValueError(\"Cannot lazy-load foreign key with auto_create=True\") from None\n\n def __repr__(self) -> str:\n \"\"\"\n An internal string representation of the table.\n\n :return: The columns of this table formatted as a string\n \"\"\"\n return pformat(self.columns)\n\n def __str__(self) -> str:\n \"\"\"\n A string representation of the table.\n\n :return: The name of the table\n \"\"\"\n return self.table_name\n\n def extract_columns(self, table_: Type[TableT]) -> Iterator[Column]:\n \"\"\"\n Extracts the declared columns from a valid class definition of a class in the schema.\n\n :param table_: The decorated table class\n :return: A generator which iterates each of the created Column objects\n \"\"\"\n\n column_information = list(filter(lambda member: not member[0].startswith(\"__\"),\n getmembers(table_, lambda member: not isroutine(member))))\n for name, column in column_information:\n yield self.amend_column(name, column)\n\n def amend_column(self, column_name: str, column_type: Type | type | ForeignKey) -> Column:\n \"\"\"\n Converts a column as defined in the schema into a valid Column object.\n\n :param column_name: The defined name of the column\n :param column_type: The defined type of the column\n :return: The valid column object to be used by SQLiteFrame\n \"\"\"\n if isinstance(column_type, type): # Plain Key\n column_type = column_type()\n return Column(self, column_name, column_type)\n\n def sort_columns(self, columns: Iterable[Column | Wildcards],\n base_columns_override: Optional[list[Column]] = None) -> list[Column]:\n \"\"\"\n Returns the given columns in the correct order as per the schema.\n\n This is used in SELECT statements to ensure that the column order\n matches with the order of columns in the returned data.\n\n :param columns: The columns to sort\n :param base_columns_override: An override mechanism for the columns to base the ordering off of\n :return: The sorted list of columns\n \"\"\"\n base_columns = self.columns if base_columns_override is None else base_columns_override\n if Wildcards.All in columns:\n return base_columns\n return sorted(columns, key=lambda column: base_columns.index(column))\n\n def set(self, data: dict[ColumnT, ColumnT.type.decoded_type]) -> Set:\n \"\"\"\n Create a SET statement which runs on this table.\n\n :param data: The data to set into this table as a valid mapping\n :return: A Set statement object, which can be operated on further.\n \"\"\"\n\n for column in data:\n if not column.is_nullable and data[column] is None:\n raise ValueError(f\"Non-nullable column '{column.name}' passed NULL\") from None\n return Set(self, data)\n\n def insert_into(self, data: dict[ColumnT, ColumnT.type.decoded_type]) -> InsertInto:\n \"\"\"\n Create an INSERT INTO statement which runs on this table.\n\n :param data: The data to set into this table as a valid mapping\n :return: An InsertInto statement object, which can be operated on further.\n \"\"\"\n\n for column in data:\n if not column.is_nullable and data[column] is None:\n raise ValueError(f\"Non-nullable column '{column.name}' passed NULL\") from None\n for column in set(self.columns) - set(data):\n if not column.is_nullable and column.default is None:\n raise ValueError(f\"Non-nullable column '{column.name}' passed NULL\") from None\n data[column] = None\n return InsertInto(self, data)\n\n def select(self, *columns: Column | Literal[Wildcards.All], distinct: bool = False) -> Select:\n \"\"\"\n Create an SELECT statement which runs on this table.\n\n :param columns: The column(s) to select\n :param distinct: Whether to select only distinct (non-duplicate) data\n :return: A Select statement object, which can be operated on further.\n \"\"\"\n\n if Wildcards.All in columns:\n columns = [Wildcards.All]\n return Select(self, list(columns), distinct=distinct)\n\n def delete_from(self) -> DeleteFrom:\n \"\"\"\n Create an DELETE FROM statement which runs on this table.\n\n :return: A DeleteFrom statement object, which can be operated on further.\n \"\"\"\n\n return DeleteFrom(self)\n\n def drop_table(self) -> DropTable:\n \"\"\"\n Create an DROP TABLE statement which runs on this table.\n\n :return: A DropTable statement object, which can be operated on further.\n \"\"\"\n\n return DropTable(self)\n\n def __getitem__(self, item: ColumnT.type.decoded_type) -> ColumnT.type.decoded_type:\n \"\"\"\n Entity[data] --> data\n\n This is method which serves only to create a more declarative API - it can be used when inserting\n or setting data into a foreign key column, to explicitly show which table the data being input\n is intended to be coming from.\n\n :param item: The data in the primary key column of this table\n :return: The same data input as a parameter\n \"\"\"\n\n return item\n\n def create_table(self) -> CreateTable:\n \"\"\"\n Create an CREATE TABLE statement which runs on this table.\n\n :return: A CreateTable statement object, which can be operated on further.\n \"\"\"\n return CreateTable(self, self.columns)\n", "shortDescription": "The module containing the logic for entities (tables) in SQLiteFrame", "longDescription": null, "deprecations": [], @@ -873,7 +873,7 @@ export const project = parseProject({ "meta": { "searchCategory": "module", "name": "foreign_key", - "source": "\"\"\"\nThe module containing logic for foreign keys.\n\"\"\"\n\nfrom __future__ import annotations\nfrom functools import cached_property\nfrom typing import TypeVar, Optional, Callable\nfrom .restraints import Restraints\nfrom ..types import Type\nif False:\n from ..entity import Entity, Column\n\n\nEncodedT = TypeVar(\"EncodedT\")\nDecodedT = TypeVar(\"DecodedT\")\n\n\nclass ForeignKey(Type[EncodedT, DecodedT]):\n \"\"\"\n The implementation for foreign keys.\n\n Inheritance from Type is an implementation detail - most of the Type implementations are delegated\n to an internal reference to this column's actual type.\n \"\"\"\n\n def __init__(self, table: Entity | Callable[[], Entity], default: Optional[DecodedT] = None,\n on_update: Restraints = Restraints.CASCADE, on_delete: Restraints = Restraints.RESTRICT,\n nullable: bool = False):\n \"\"\"\n :param table: The table this column is a part of\n :param default: The default value of this column\n :param on_update: The on update restraint of this column\n :param on_delete: The on delete restraint of this column\n :param nullable: Whether this column is nullable\n \"\"\"\n self._table = table\n self.on_update = on_update\n self.on_delete = on_delete\n super().__init__(nullable=nullable, default=default)\n\n @cached_property\n def table(self) -> Entity:\n \"\"\"\n A lazy cached property to get the table this column is a part of.\n\n :return: The table this column is a part of\n \"\"\"\n from ..entity import Entity\n if not isinstance(self._table, Entity):\n return self._table()\n return self._table\n\n @cached_property\n def foreign_column(self) -> Column:\n \"\"\"\n A cached property to get the primary key column of the table this foreign key references.\n\n :return: The primary key column of the table this foreign key references\n \"\"\"\n return next(filter(lambda column: column.is_primary_key, self.table.columns))\n\n def sql_name(self) -> str:\n return self.foreign_column.type.sql_name()\n\n def encode(self, decoded: DecodedT) -> EncodedT:\n return self.foreign_column.type.encode(decoded)\n\n def decode(self, encoded: EncodedT) -> DecodedT:\n return self.foreign_column.type.decode(encoded)\n\n @property\n def encoded_type(self) -> type:\n return self.foreign_column.type.encoded_type\n\n @property\n def decoded_type(self) -> type:\n return self.foreign_column.type.decoded_type\n\n def sql_restraint(self, column: Column) -> str:\n \"\"\"\n Builds the SQL for this column's restraints when updating and deleting this column.\n\n :param column: The column to define as foreign\n :return: A valid SQL string to be used in a CREATE TABLE statement\n \"\"\"\n return f\"FOREIGN KEY ({column.name}) REFERENCES {self.table} ({self.foreign_column.name})\\n\" \\\n f\"\\tON UPDATE {self.on_update.value}\\n\\tON DELETE {self.on_delete.value}\"\n\n def __str__(self) -> str:\n \"\"\"\n The string representation for this column, used when it is being executed.\n\n :return: The valid SQL string representing this column\n \"\"\"\n\n not_null = \"\" if self.nullable else \" NOT NULL\"\n return f\"{self.sql_name()}{not_null}\"\n\n def default_suggestion(self, encoded: EncodedT) -> str:\n return \"ForeignKey\"\n", + "source": "\"\"\"\nThe module containing logic for foreign keys.\n\"\"\"\n\nfrom __future__ import annotations\nfrom functools import cached_property\nfrom typing import TypeVar, Optional, Callable, TYPE_CHECKING\nfrom .restraints import Restraints\nfrom ..types import Type\nif TYPE_CHECKING:\n from ..entity import Entity, Column\n\n\nEncodedT = TypeVar(\"EncodedT\")\nDecodedT = TypeVar(\"DecodedT\")\n\n\nclass ForeignKey(Type[EncodedT, DecodedT]):\n \"\"\"\n The implementation for foreign keys.\n\n Inheritance from Type is an implementation detail - most of the Type implementations are delegated\n to an internal reference to this column's actual type.\n \"\"\"\n\n def __init__(self, table: Entity | Callable[[], Entity], default: Optional[DecodedT] = None,\n on_update: Restraints = Restraints.CASCADE, on_delete: Restraints = Restraints.RESTRICT,\n nullable: bool = False):\n \"\"\"\n :param table: The table this column is a part of\n :param default: The default value of this column\n :param on_update: The on update restraint of this column\n :param on_delete: The on delete restraint of this column\n :param nullable: Whether this column is nullable\n \"\"\"\n self._table = table\n self.on_update = on_update\n self.on_delete = on_delete\n super().__init__(nullable=nullable, default=default)\n\n @cached_property\n def table(self) -> Entity:\n \"\"\"\n A lazy cached property to get the table this column is a part of.\n\n :return: The table this column is a part of\n \"\"\"\n from ..entity import Entity\n if not isinstance(self._table, Entity):\n return self._table()\n return self._table\n\n @cached_property\n def foreign_column(self) -> Column:\n \"\"\"\n A cached property to get the primary key column of the table this foreign key references.\n\n :return: The primary key column of the table this foreign key references\n \"\"\"\n return next(filter(lambda column: column.is_primary_key, self.table.columns))\n\n def sql_name(self) -> str:\n return self.foreign_column.type.sql_name()\n\n def encode(self, decoded: DecodedT) -> EncodedT:\n return self.foreign_column.type.encode(decoded)\n\n def decode(self, encoded: EncodedT) -> DecodedT:\n return self.foreign_column.type.decode(encoded)\n\n @property\n def encoded_type(self) -> type:\n return self.foreign_column.type.encoded_type\n\n @property\n def decoded_type(self) -> type:\n return self.foreign_column.type.decoded_type\n\n def sql_restraint(self, column: Column) -> str:\n \"\"\"\n Builds the SQL for this column's restraints when updating and deleting this column.\n\n :param column: The column to define as foreign\n :return: A valid SQL string to be used in a CREATE TABLE statement\n \"\"\"\n return f\"FOREIGN KEY ({column.name}) REFERENCES {self.table} ({self.foreign_column.name})\\n\" \\\n f\"\\tON UPDATE {self.on_update.value}\\n\\tON DELETE {self.on_delete.value}\"\n\n def __str__(self) -> str:\n \"\"\"\n The string representation for this column, used when it is being executed.\n\n :return: The valid SQL string representing this column\n \"\"\"\n\n not_null = \"\" if self.nullable else \" NOT NULL\"\n return f\"{self.sql_name()}{not_null}\"\n\n def default_suggestion(self, encoded: EncodedT) -> str:\n return \"ForeignKey\"\n", "shortDescription": "The module containing logic for foreign keys.", "longDescription": null, "deprecations": [], @@ -1446,7 +1446,7 @@ export const project = parseProject({ "meta": { "searchCategory": "module", "name": "join", - "source": "\"\"\"\nThe module containing the logic for JOIN clauses.\n\"\"\"\n\nfrom __future__ import annotations\nfrom .join_types import JoinTypes\nfrom ..where import Condition, Where\nif False:\n from sqliteframe.entity import Entity\n\n\nclass Join:\n \"\"\"\n The class containing the implementation for JOIN clauses.\n \"\"\"\n\n def __init__(self, table: Entity, where: Where | Condition, join_type: JoinTypes):\n \"\"\"\n :param table: The table being joined\n :param where: The conditions under which this join statement is used\n :param join_type: The way in which the table is joined\n \"\"\"\n super().__init__()\n self.table = table\n self.where = where\n self.join_type = join_type\n\n def __str__(self) -> str:\n \"\"\"\n The string representation for this clause, used when it is being executed.\n\n :return: The valid SQL string representing this clause\n \"\"\"\n\n return f\"{self.join_type.value} JOIN {self.table} ON {self.where}\"\n", + "source": "\"\"\"\nThe module containing the logic for JOIN clauses.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import TYPE_CHECKING\nfrom .join_types import JoinTypes\nfrom ..where import Condition, Where\nif TYPE_CHECKING:\n from sqliteframe.entity import Entity\n\n\nclass Join:\n \"\"\"\n The class containing the implementation for JOIN clauses.\n \"\"\"\n\n def __init__(self, table: Entity, where: Where | Condition, join_type: JoinTypes):\n \"\"\"\n :param table: The table being joined\n :param where: The conditions under which this join statement is used\n :param join_type: The way in which the table is joined\n \"\"\"\n super().__init__()\n self.table = table\n self.where = where\n self.join_type = join_type\n\n def __str__(self) -> str:\n \"\"\"\n The string representation for this clause, used when it is being executed.\n\n :return: The valid SQL string representing this clause\n \"\"\"\n\n return f\"{self.join_type.value} JOIN {self.table} ON {self.where}\"\n", "shortDescription": "The module containing the logic for JOIN clauses.", "longDescription": null, "deprecations": [], @@ -1685,7 +1685,7 @@ export const project = parseProject({ "meta": { "searchCategory": "module", "name": "order_by", - "source": "\"\"\"\nThe module containing the logic for ORDER BY clauses.\n\"\"\"\n\nfrom __future__ import annotations\nfrom .order_types import OrderTypes\nif False:\n from sqliteframe.entity import Column\n\n\nclass OrderBy:\n \"\"\"\n The class containing the implementation for ORDER BY clauses.\n \"\"\"\n\n def __init__(self, column: Column, order_types: OrderTypes | tuple[OrderTypes, ...]):\n \"\"\"\n :param column: The target column to order by\n :param order_types: The order type(s) to order by\n \"\"\"\n self.column = column\n self.order_types = (order_types, ) if isinstance(order_types, OrderTypes) else order_types\n if (OrderTypes.ASCENDING in self.order_types and OrderTypes.DESCENDING in self.order_types) or (\n OrderTypes.NULLS_FIRST in self.order_types and OrderTypes.NULLS_LAST in self.order_types):\n raise ValueError(\"SQL query cannot contain conflicting order by statement\") from None\n\n def __str__(self) -> str:\n \"\"\"\n The string representation for this clause, used when it is being executed.\n\n :return: The valid SQL string representing this clause\n \"\"\"\n\n order_type_section = \" \".join(map(lambda order_type: order_type.value, self.order_types))\n return f\"ORDER BY {self.column.table}.{self.column.name} {order_type_section}\"\n", + "source": "\"\"\"\nThe module containing the logic for ORDER BY clauses.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import TYPE_CHECKING\nfrom .order_types import OrderTypes\nif TYPE_CHECKING:\n from sqliteframe.entity import Column\n\n\nclass OrderBy:\n \"\"\"\n The class containing the implementation for ORDER BY clauses.\n \"\"\"\n\n def __init__(self, column: Column, order_types: OrderTypes | tuple[OrderTypes, ...]):\n \"\"\"\n :param column: The target column to order by\n :param order_types: The order type(s) to order by\n \"\"\"\n self.column = column\n self.order_types = (order_types, ) if isinstance(order_types, OrderTypes) else order_types\n if (OrderTypes.ASCENDING in self.order_types and OrderTypes.DESCENDING in self.order_types) or (\n OrderTypes.NULLS_FIRST in self.order_types and OrderTypes.NULLS_LAST in self.order_types):\n raise ValueError(\"SQL query cannot contain conflicting order by statement\") from None\n\n def __str__(self) -> str:\n \"\"\"\n The string representation for this clause, used when it is being executed.\n\n :return: The valid SQL string representing this clause\n \"\"\"\n\n order_type_section = \" \".join(map(lambda order_type: order_type.value, self.order_types))\n return f\"ORDER BY {self.column.table}.{self.column.name} {order_type_section}\"\n", "shortDescription": "The module containing the logic for ORDER BY clauses.", "longDescription": null, "deprecations": [], @@ -1922,7 +1922,7 @@ export const project = parseProject({ "meta": { "searchCategory": "module", "name": "parameterized", - "source": "\"\"\"\nThe module containing the logic behind Parameterized clauses.\n\"\"\"\n\nfrom __future__ import annotations\nfrom abc import ABC, abstractmethod\nfrom typing import Literal\n\nif False:\n from ..statements import Statement\n\n\nclass Parameterized(ABC):\n \"\"\"\n The class containing the logic behind Parameterized clauses.\n\n Parameterized clauses are essentially clauses that may require use parameter sanitization, such as WHERE clauses.\n These are needed to transfer the parameters to the base statement while preserved their order,\n so that they can be passed to the internal sqlite3 engine in the correct order during execution,\n maintaining safety from SQL injection attacks.\n \"\"\"\n def parameter(self, parameter: object) -> Literal[\"?\"]:\n \"\"\"\n Registers a parameter with the clause, and converts it into a \"?\" string literal for use in the query.\n\n :param parameter: The data to register as a parameter\n :return: A \"?\" string literal\n \"\"\"\n self.parameters.append(parameter)\n return \"?\"\n\n @property\n @abstractmethod\n def parameters(self) -> list[object]:\n \"\"\"\n The parameters of this parameterized clause as an abstract property.\n\n :return: The list of parameters\n \"\"\"\n return []\n\n @abstractmethod\n def build_sql(self) -> str:\n \"\"\"\n Builds a valid SQL string representing this clause, used when executing the statement this clause is a part of.\n\n :return: The valid SQL string representing this clause\n \"\"\"\n return \"\"\n\n def __str__(self) -> str:\n \"\"\"\n The string representation for this clause, used when it is being executed.\n\n :return: The valid SQL string representing this clause\n \"\"\"\n return self.build_sql()\n\n def register(self, statement: Statement) -> None:\n \"\"\"\n Registers each of the parameters of this clause with a given base statement.\n\n :param statement: The base statement this clause is a part of\n \"\"\"\n statement.register_parameterized(self)\n", + "source": "\"\"\"\nThe module containing the logic behind Parameterized clauses.\n\"\"\"\n\nfrom __future__ import annotations\nfrom abc import ABC, abstractmethod\nfrom typing import Literal, TYPE_CHECKING\nif TYPE_CHECKING:\n from ..statements import Statement\n\n\nclass Parameterized(ABC):\n \"\"\"\n The class containing the logic behind Parameterized clauses.\n\n Parameterized clauses are essentially clauses that may require use parameter sanitization, such as WHERE clauses.\n These are needed to transfer the parameters to the base statement while preserved their order,\n so that they can be passed to the internal sqlite3 engine in the correct order during execution,\n maintaining safety from SQL injection attacks.\n \"\"\"\n def parameter(self, parameter: object) -> Literal[\"?\"]:\n \"\"\"\n Registers a parameter with the clause, and converts it into a \"?\" string literal for use in the query.\n\n :param parameter: The data to register as a parameter\n :return: A \"?\" string literal\n \"\"\"\n self.parameters.append(parameter)\n return \"?\"\n\n @property\n @abstractmethod\n def parameters(self) -> list[object]:\n \"\"\"\n The parameters of this parameterized clause as an abstract property.\n\n :return: The list of parameters\n \"\"\"\n return []\n\n @abstractmethod\n def build_sql(self) -> str:\n \"\"\"\n Builds a valid SQL string representing this clause, used when executing the statement this clause is a part of.\n\n :return: The valid SQL string representing this clause\n \"\"\"\n return \"\"\n\n def __str__(self) -> str:\n \"\"\"\n The string representation for this clause, used when it is being executed.\n\n :return: The valid SQL string representing this clause\n \"\"\"\n return self.build_sql()\n\n def register(self, statement: Statement) -> None:\n \"\"\"\n Registers each of the parameters of this clause with a given base statement.\n\n :param statement: The base statement this clause is a part of\n \"\"\"\n statement.register_parameterized(self)\n", "shortDescription": "The module containing the logic behind Parameterized clauses.", "longDescription": null, "deprecations": [], @@ -2498,7 +2498,7 @@ export const project = parseProject({ "meta": { "searchCategory": "module", "name": "result", - "source": "\"\"\"\nA module containing the logic for SQLiteFrame Result objects.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import Iterator\nfrom sqlite3 import Cursor\nif False:\n from typing import TypeVar\n from sqliteframe.entity import Column\n ColumnT = TypeVar(\"ColumnT\", bound=Column)\n\n\nclass Result:\n \"\"\"\n The class that contains result data from any executed SQLiteFrame queries.\n \"\"\"\n\n UNKNOWN_COLUMN = \"?\"\n\n def __init__(self, columns: list[Column], result: Cursor, indeterminate: bool = False):\n self.columns = columns\n self.result = result\n self.indeterminate_columns = indeterminate\n\n def __iter__(self) -> Iterator[dict[ColumnT, ColumnT.type.decoded_type] | tuple]:\n \"\"\"\n Allows for records to be accessed from a Result via simple iteration (e.g. for record in result).\n\n :return: An iterator containing each record, usually as a mapping ({column: data})\n \"\"\"\n for record in self.result:\n if self.indeterminate_columns:\n yield record\n else:\n yield {column: column.type.decode(field) for column, field in zip(self.columns, record)}\n", + "source": "\"\"\"\nA module containing the logic for SQLiteFrame Result objects.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import Iterator, TypeVar, TYPE_CHECKING\nfrom sqlite3 import Cursor\nif TYPE_CHECKING:\n from sqliteframe.entity import Column\n ColumnT = TypeVar(\"ColumnT\", bound=Column)\n\n\nclass Result:\n \"\"\"\n The class that contains result data from any executed SQLiteFrame queries.\n \"\"\"\n\n UNKNOWN_COLUMN = \"?\"\n\n def __init__(self, columns: list[Column], result: Cursor, indeterminate: bool = False):\n self.columns = columns\n self.result = result\n self.indeterminate_columns = indeterminate\n\n def __iter__(self) -> Iterator[dict[ColumnT, ColumnT.type.decoded_type] | tuple]:\n \"\"\"\n Allows for records to be accessed from a Result via simple iteration (e.g. for record in result).\n\n :return: An iterator containing each record, usually as a mapping ({column: data})\n \"\"\"\n for record in self.result:\n if self.indeterminate_columns:\n yield record\n else:\n yield {column: column.type.decode(field) for column, field in zip(self.columns, record)}\n", "shortDescription": "A module containing the logic for SQLiteFrame Result objects.", "longDescription": null, "deprecations": [], @@ -2606,7 +2606,7 @@ export const project = parseProject({ "meta": { "searchCategory": "module", "name": "create_table", - "source": "\"\"\"\nThe module containing logic for CREATE TABLE statements.\n\"\"\"\n\nfrom __future__ import annotations\nfrom .statement import Statement\nif False:\n from ..entity import Column, Entity\n\n\nclass CreateTable(Statement):\n \"\"\"\n The class containing the logic for building and executing CREATE TABLE statements with SQLiteFrame.\n \"\"\"\n\n def __init__(self, table: Entity, columns: list[Column]):\n \"\"\"\n\n :param table: The table this query is associated with\n :param columns: The columns the table being created should have\n \"\"\"\n super().__init__(table.database)\n self.table = table\n self.columns = columns\n self.foreign_key_columns = list(filter(lambda column: column.is_foreign_key, self.columns))\n\n def build_sql(self) -> str:\n columns_section = \"\\n\".join(f\"\\t{column.name} {column},\" for column in self.columns)\n if not self.foreign_key_columns:\n columns_section = columns_section[:-1]\n foreign_key_section = (\"\\n\\n\\t\" if self.foreign_key_columns else \"\") + \"\\n\".join(\n column.type.sql_restraint(column).replace(\"\\n\", \"\\n\\t\") for column in self.foreign_key_columns)\n return f\"CREATE TABLE IF NOT EXISTS {self.table} (\\n{columns_section}{foreign_key_section}\\n);\"\n", + "source": "\"\"\"\nThe module containing logic for CREATE TABLE statements.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import TYPE_CHECKING\nfrom .statement import Statement\nif TYPE_CHECKING:\n from ..entity import Column, Entity\n\n\nclass CreateTable(Statement):\n \"\"\"\n The class containing the logic for building and executing CREATE TABLE statements with SQLiteFrame.\n \"\"\"\n\n def __init__(self, table: Entity, columns: list[Column]):\n \"\"\"\n\n :param table: The table this query is associated with\n :param columns: The columns the table being created should have\n \"\"\"\n super().__init__(table.database)\n self.table = table\n self.columns = columns\n self.foreign_key_columns = list(filter(lambda column: column.is_foreign_key, self.columns))\n\n def build_sql(self) -> str:\n columns_section = \"\\n\".join(f\"\\t{column.name} {column},\" for column in self.columns)\n if not self.foreign_key_columns:\n columns_section = columns_section[:-1]\n foreign_key_section = (\"\\n\\n\\t\" if self.foreign_key_columns else \"\") + \"\\n\".join(\n column.type.sql_restraint(column).replace(\"\\n\", \"\\n\\t\") for column in self.foreign_key_columns)\n return f\"CREATE TABLE IF NOT EXISTS {self.table} (\\n{columns_section}{foreign_key_section}\\n);\"\n", "shortDescription": "The module containing logic for CREATE TABLE statements.", "longDescription": null, "deprecations": [], @@ -2730,7 +2730,7 @@ export const project = parseProject({ "meta": { "searchCategory": "module", "name": "delete_from", - "source": "\"\"\"\nThe module containing logic for DELETE FROM statements.\n\"\"\"\n\nfrom __future__ import annotations\nfrom .statement import Statement\nfrom ..where import Where, Condition\nif False:\n from ..entity import Entity\n\n\nclass DeleteFrom(Statement):\n \"\"\"\n The class containing the logic for building and executing DELETE FROM statements with SQLiteFrame.\n \"\"\"\n\n def __init__(self, table: Entity):\n \"\"\"\n :param table: The table this query is associated with\n \"\"\"\n super().__init__(table.database)\n self.table = table\n self.where_statement = None\n\n def build_sql(self) -> str:\n where_section = \"\" if self.where is None else f\"\\nWHERE {self.where_statement}\"\n return f\"DELETE FROM {self.table}{where_section};\"\n\n def where(self, where: Where | Condition) -> DeleteFrom:\n \"\"\"\n A method to attach WHERE clauses onto the DELETE FROM statement\n\n :param where: The WHERE clause to add to the statement\n :return: A mutated version of this statement with the extended WHERE clause\n \"\"\"\n\n if self.where_statement is None:\n where.register(self)\n self.where_statement = where\n else:\n self.where_statement &= where\n return self\n", + "source": "\"\"\"\nThe module containing logic for DELETE FROM statements.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import TYPE_CHECKING\nfrom .statement import Statement\nfrom ..where import Where, Condition\nif TYPE_CHECKING:\n from ..entity import Entity\n\n\nclass DeleteFrom(Statement):\n \"\"\"\n The class containing the logic for building and executing DELETE FROM statements with SQLiteFrame.\n \"\"\"\n\n def __init__(self, table: Entity):\n \"\"\"\n :param table: The table this query is associated with\n \"\"\"\n super().__init__(table.database)\n self.table = table\n self.where_statement = None\n\n def build_sql(self) -> str:\n where_section = \"\" if self.where is None else f\"\\nWHERE {self.where_statement}\"\n return f\"DELETE FROM {self.table}{where_section};\"\n\n def where(self, where: Where | Condition) -> DeleteFrom:\n \"\"\"\n A method to attach WHERE clauses onto the DELETE FROM statement\n\n :param where: The WHERE clause to add to the statement\n :return: A mutated version of this statement with the extended WHERE clause\n \"\"\"\n\n if self.where_statement is None:\n where.register(self)\n self.where_statement = where\n else:\n self.where_statement &= where\n return self\n", "shortDescription": "The module containing logic for DELETE FROM statements.", "longDescription": null, "deprecations": [], @@ -2900,7 +2900,7 @@ export const project = parseProject({ "meta": { "searchCategory": "module", "name": "drop_table", - "source": "\"\"\"\nThe module containing logic for DROP TABLE statements.\n\"\"\"\n\nfrom __future__ import annotations\nfrom .statement import Statement\nif False:\n from ..entity import Entity\n\n\nclass DropTable(Statement):\n \"\"\"\n The class containing the logic for building and executing DROP TABLE statements with SQLiteFrame.\n \"\"\"\n\n def __init__(self, table: Entity):\n \"\"\"\n :param table: The table this query is associated with\n \"\"\"\n super().__init__(table.database)\n self.table = table\n\n def build_sql(self) -> str:\n return f\"DROP TABLE IF EXISTS {self.table};\"\n", + "source": "\"\"\"\nThe module containing logic for DROP TABLE statements.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import TYPE_CHECKING\nfrom .statement import Statement\nif TYPE_CHECKING:\n from ..entity import Entity\n\n\nclass DropTable(Statement):\n \"\"\"\n The class containing the logic for building and executing DROP TABLE statements with SQLiteFrame.\n \"\"\"\n\n def __init__(self, table: Entity):\n \"\"\"\n :param table: The table this query is associated with\n \"\"\"\n super().__init__(table.database)\n self.table = table\n\n def build_sql(self) -> str:\n return f\"DROP TABLE IF EXISTS {self.table};\"\n", "shortDescription": "The module containing logic for DROP TABLE statements.", "longDescription": null, "deprecations": [], @@ -3013,7 +3013,7 @@ export const project = parseProject({ "meta": { "searchCategory": "module", "name": "insert_into", - "source": "\"\"\"\nThe module containing logic for INSERT INTO statements.\n\"\"\"\n\nfrom __future__ import annotations\nfrom .statement import Statement\nif False:\n from typing import TypeVar\n from ..entity import Column, Entity\n ColumnT = TypeVar(\"ColumnT\", bound=Column)\n\n\nclass InsertInto(Statement):\n \"\"\"\n The class containing the logic for building and executing INSERT INTO statements with SQLiteFrame.\n \"\"\"\n\n def __init__(self, table: Entity, data: dict[ColumnT, ColumnT.type.decoded_type]):\n \"\"\"\n :param table: The table this query is associated with\n :param data: A mapping of the column and corresponding data to insert into the given table\n \"\"\"\n super().__init__(table.database)\n self.table = table\n self.data = data.items()\n\n def build_sql(self) -> str:\n columns_section = \", \".join(column.name for column, _ in self.data)\n values_section = \", \".join(self.parameter(column.type.encode(value)) for column, value in self.data)\n return f\"INSERT INTO {self.table} ({columns_section})\\nVALUES ({values_section});\"\n", + "source": "\"\"\"\nThe module containing logic for INSERT INTO statements.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import TypeVar, TYPE_CHECKING\nfrom .statement import Statement\nif TYPE_CHECKING:\n from ..entity import Column, Entity\n ColumnT = TypeVar(\"ColumnT\", bound=Column)\n\n\nclass InsertInto(Statement):\n \"\"\"\n The class containing the logic for building and executing INSERT INTO statements with SQLiteFrame.\n \"\"\"\n\n def __init__(self, table: Entity, data: dict[ColumnT, ColumnT.type.decoded_type]):\n \"\"\"\n :param table: The table this query is associated with\n :param data: A mapping of the column and corresponding data to insert into the given table\n \"\"\"\n super().__init__(table.database)\n self.table = table\n self.data = data.items()\n\n def build_sql(self) -> str:\n columns_section = \", \".join(column.name for column, _ in self.data)\n values_section = \", \".join(self.parameter(column.type.encode(value)) for column, value in self.data)\n return f\"INSERT INTO {self.table} ({columns_section})\\nVALUES ({values_section});\"\n", "shortDescription": "The module containing logic for INSERT INTO statements.", "longDescription": null, "deprecations": [], @@ -3137,7 +3137,7 @@ export const project = parseProject({ "meta": { "searchCategory": "module", "name": "pragma", - "source": "\"\"\"\nThe module containing logic for PRAGMA statements.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import Optional\nfrom .statement import Statement\nfrom ..pragma import PragmaStatements, PragmaTypes\nif False:\n from ..database import Database\n\n\nclass Pragma(Statement):\n \"\"\"\n The class containing the logic for building and executing PRAGMA statements with SQLiteFrame.\n \"\"\"\n\n def __init__(self, database: Database, pragma_statement: PragmaStatements,\n pragma_value: Optional[str] = None, pragma_type: PragmaTypes = PragmaTypes.SET):\n \"\"\"\n :param database: The database this statement is associated with\n :param pragma_statement: The type of PRAGMA statement to execute\n :param pragma_value: The value associated with the PRAGMA statement\n :param pragma_type: The structure of the PRAGMA statement\n \"\"\"\n super().__init__(database, indeterminate_yield=pragma_type != PragmaTypes.QUERY)\n self.statement = pragma_statement\n self.value = pragma_value\n self.type = pragma_type\n if self.value is None and self.type != PragmaTypes.QUERY:\n raise ValueError(\"PRAGMA statement cannot have no value when using QUERY mode\") from None\n\n def build_sql(self) -> str:\n return f\"PRAGMA {self.statement.value}{self.type.value(self.value)};\"\n", + "source": "\"\"\"\nThe module containing logic for PRAGMA statements.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import Optional, TYPE_CHECKING\nfrom .statement import Statement\nfrom ..pragma import PragmaStatements, PragmaTypes\nif TYPE_CHECKING:\n from ..database import Database\n\n\nclass Pragma(Statement):\n \"\"\"\n The class containing the logic for building and executing PRAGMA statements with SQLiteFrame.\n \"\"\"\n\n def __init__(self, database: Database, pragma_statement: PragmaStatements,\n pragma_value: Optional[str] = None, pragma_type: PragmaTypes = PragmaTypes.SET):\n \"\"\"\n :param database: The database this statement is associated with\n :param pragma_statement: The type of PRAGMA statement to execute\n :param pragma_value: The value associated with the PRAGMA statement\n :param pragma_type: The structure of the PRAGMA statement\n \"\"\"\n super().__init__(database, indeterminate_yield=pragma_type != PragmaTypes.QUERY)\n self.statement = pragma_statement\n self.value = pragma_value\n self.type = pragma_type\n if self.value is None and self.type != PragmaTypes.QUERY:\n raise ValueError(\"PRAGMA statement cannot have no value when using QUERY mode\") from None\n\n def build_sql(self) -> str:\n return f\"PRAGMA {self.statement.value}{self.type.value(self.value)};\"\n", "shortDescription": "The module containing logic for PRAGMA statements.", "longDescription": null, "deprecations": [], @@ -3155,7 +3155,7 @@ export const project = parseProject({ "searchCategory": "class", "name": "Pragma", "source": "class Pragma(Statement):\n \"\"\"\n The class containing the logic for building and executing PRAGMA statements with SQLiteFrame.\n \"\"\"\n\n def __init__(self, database: Database, pragma_statement: PragmaStatements,\n pragma_value: Optional[str] = None, pragma_type: PragmaTypes = PragmaTypes.SET):\n \"\"\"\n :param database: The database this statement is associated with\n :param pragma_statement: The type of PRAGMA statement to execute\n :param pragma_value: The value associated with the PRAGMA statement\n :param pragma_type: The structure of the PRAGMA statement\n \"\"\"\n super().__init__(database, indeterminate_yield=pragma_type != PragmaTypes.QUERY)\n self.statement = pragma_statement\n self.value = pragma_value\n self.type = pragma_type\n if self.value is None and self.type != PragmaTypes.QUERY:\n raise ValueError(\"PRAGMA statement cannot have no value when using QUERY mode\") from None\n\n def build_sql(self) -> str:\n return f\"PRAGMA {self.statement.value}{self.type.value(self.value)};\"\n", - "signature": "(database: 'Database', pragma_statement: 'PragmaStatements', pragma_value: 'Optional[str]' = None, pragma_type: 'PragmaTypes' = >)", + "signature": "(database: 'Database', pragma_statement: 'PragmaStatements', pragma_value: 'Optional[str]' = None, pragma_type: 'PragmaTypes' = >)", "parameters": [ { "component": "Parameter", @@ -3283,7 +3283,7 @@ export const project = parseProject({ "meta": { "searchCategory": "module", "name": "select", - "source": "\"\"\"\nThe module containing logic for SELECT statements.\n\"\"\"\n\nfrom __future__ import annotations\nfrom .statement import Statement\nfrom ..wildcards import Wildcards\nfrom ..order_by import OrderBy, OrderTypes\nfrom ..where import Where, Condition\nfrom ..join import Join, JoinTypes\nif False:\n from ..entity import Column, Entity\n\n\nclass Select(Statement):\n \"\"\"\n The class containing the logic for building and executing SELECT statements with SQLiteFrame.\n \"\"\"\n\n def __init__(self, table: Entity, columns: list[Column | Wildcards], distinct: bool = False):\n \"\"\"\n :param table: The table this query is associated with\n :param columns: The column(s) to select from\n :param distinct: Whether to select only non-duplicate (distinct) values\n \"\"\"\n super().__init__(table.database, yield_column_factory=lambda: self.columns)\n self.table = table\n if not filter(lambda column: column not in [wildcard.value for wildcard in Wildcards],\n set(columns) - set(self.table.columns)):\n columns = set(sorted(columns, key=lambda column: self.table.columns.index(column)))\n self.passed_columns = columns\n self.columns = self.table.columns if Wildcards.All in columns else self.passed_columns[:]\n self.distinct = distinct\n self.where_statement = None\n self.join_statements = []\n self.order_by_statement = None\n\n def build_sql(self) -> str:\n distinct_section = \" DISTINCT\" if self.distinct else \"\"\n columns_section = \", \".join(map(lambda column: column.name, self.columns))\n join_section = (\"\\n\" + \"\\n\".join(map(str, self.join_statements))) if self.join_statements else \"\"\n where_section = \"\" if self.where_statement is None else f\"\\nWHERE {self.where_statement}\"\n order_by_section = \"\" if self.order_by_statement is None else f\"\\n{self.order_by_statement}\"\n return f\"SELECT{distinct_section} {columns_section}\\n\" \\\n f\"FROM {self.table}{join_section}{where_section}{order_by_section};\"\n\n def where(self, where: Where | Condition) -> Select:\n \"\"\"\n A method to attach WHERE clauses onto the SELECT statement\n\n :param where: The WHERE clause to add to the statement\n :return: A mutated version of this statement with the extended WHERE clause\n \"\"\"\n\n if self.where_statement is None:\n where.register(self)\n self.where_statement = where\n else:\n self.where_statement &= where\n return self\n\n def join(self, table: Entity, where: Where | Condition, join_type: JoinTypes = JoinTypes.INNER) -> Select:\n \"\"\"\n A method to attach JOIN clauses onto the SELECT statement.\n\n :param table: The table to join with\n :param where: The WHERE clause to add to the statement\n :param join_type: The way in which the tables should be joined\n :return: A mutated version of this statement with the extended WHERE clause\n \"\"\"\n\n if Wildcards.All in self.passed_columns:\n self.columns = self.columns + table.columns if join_type == JoinTypes.LEFT else table.columns + self.columns\n else:\n joined_columns = table.sort_columns(set(self.columns) - set(self.table.columns),\n base_columns_override=self.passed_columns)\n original_columns = self.table.sort_columns(set(self.columns) - set(joined_columns),\n base_columns_override=self.passed_columns)\n self.columns = joined_columns + original_columns if join_type == JoinTypes.LEFT else \\\n original_columns + joined_columns\n self.join_statements.append(Join(table, where, join_type))\n return self\n\n def order_by(self, column: Column,\n order_types: OrderTypes | tuple[OrderTypes, ...] = OrderTypes.ASCENDING) -> Select:\n \"\"\"\n A method to attach ORDER BY clauses onto the SELECT statement.\n\n :param column: The target column to order by\n :param order_types: The way in which the results should be ordered\n :return: A mutated version of this statement with the extended ORDER BY clause\n \"\"\"\n self.order_by_statement = OrderBy(column, order_types)\n return self\n", + "source": "\"\"\"\nThe module containing logic for SELECT statements.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import TYPE_CHECKING\nfrom .statement import Statement\nfrom ..wildcards import Wildcards\nfrom ..order_by import OrderBy, OrderTypes\nfrom ..where import Where, Condition\nfrom ..join import Join, JoinTypes\nif TYPE_CHECKING:\n from ..entity import Column, Entity\n\n\nclass Select(Statement):\n \"\"\"\n The class containing the logic for building and executing SELECT statements with SQLiteFrame.\n \"\"\"\n\n def __init__(self, table: Entity, columns: list[Column | Wildcards], distinct: bool = False):\n \"\"\"\n :param table: The table this query is associated with\n :param columns: The column(s) to select from\n :param distinct: Whether to select only non-duplicate (distinct) values\n \"\"\"\n super().__init__(table.database, yield_column_factory=lambda: self.columns)\n self.table = table\n if not filter(lambda column: column not in [wildcard.value for wildcard in Wildcards],\n set(columns) - set(self.table.columns)):\n columns = set(sorted(columns, key=lambda column: self.table.columns.index(column)))\n self.passed_columns = columns\n self.columns = self.table.columns if Wildcards.All in columns else self.passed_columns[:]\n self.distinct = distinct\n self.where_statement = None\n self.join_statements = []\n self.order_by_statement = None\n\n def build_sql(self) -> str:\n distinct_section = \" DISTINCT\" if self.distinct else \"\"\n columns_section = \", \".join(map(lambda column: column.name, self.columns))\n join_section = (\"\\n\" + \"\\n\".join(map(str, self.join_statements))) if self.join_statements else \"\"\n where_section = \"\" if self.where_statement is None else f\"\\nWHERE {self.where_statement}\"\n order_by_section = \"\" if self.order_by_statement is None else f\"\\n{self.order_by_statement}\"\n return f\"SELECT{distinct_section} {columns_section}\\n\" \\\n f\"FROM {self.table}{join_section}{where_section}{order_by_section};\"\n\n def where(self, where: Where | Condition) -> Select:\n \"\"\"\n A method to attach WHERE clauses onto the SELECT statement\n\n :param where: The WHERE clause to add to the statement\n :return: A mutated version of this statement with the extended WHERE clause\n \"\"\"\n\n if self.where_statement is None:\n where.register(self)\n self.where_statement = where\n else:\n self.where_statement &= where\n return self\n\n def join(self, table: Entity, where: Where | Condition, join_type: JoinTypes = JoinTypes.INNER) -> Select:\n \"\"\"\n A method to attach JOIN clauses onto the SELECT statement.\n\n :param table: The table to join with\n :param where: The WHERE clause to add to the statement\n :param join_type: The way in which the tables should be joined\n :return: A mutated version of this statement with the extended WHERE clause\n \"\"\"\n\n if Wildcards.All in self.passed_columns:\n self.columns = self.columns + table.columns if join_type == JoinTypes.LEFT else table.columns + self.columns\n else:\n joined_columns = table.sort_columns(set(self.columns) - set(self.table.columns),\n base_columns_override=self.passed_columns)\n original_columns = self.table.sort_columns(set(self.columns) - set(joined_columns),\n base_columns_override=self.passed_columns)\n self.columns = joined_columns + original_columns if join_type == JoinTypes.LEFT else \\\n original_columns + joined_columns\n self.join_statements.append(Join(table, where, join_type))\n return self\n\n def order_by(self, column: Column,\n order_types: OrderTypes | tuple[OrderTypes, ...] = OrderTypes.ASCENDING) -> Select:\n \"\"\"\n A method to attach ORDER BY clauses onto the SELECT statement.\n\n :param column: The target column to order by\n :param order_types: The way in which the results should be ordered\n :return: A mutated version of this statement with the extended ORDER BY clause\n \"\"\"\n self.order_by_statement = OrderBy(column, order_types)\n return self\n", "shortDescription": "The module containing logic for SELECT statements.", "longDescription": null, "deprecations": [], @@ -3622,7 +3622,7 @@ export const project = parseProject({ "meta": { "searchCategory": "module", "name": "set", - "source": "\"\"\"\nThe module containing logic for SET statements.\n\"\"\"\n\nfrom __future__ import annotations\nfrom .statement import Statement\nfrom ..where import Where\nif False:\n from typing import TypeVar\n from ..entity import Column, Entity\n ColumnT = TypeVar(\"ColumnT\", bound=Column)\n\n\nclass Set(Statement):\n \"\"\"\n The class containing the logic for building and executing SET statements with SQLiteFrame.\n \"\"\"\n\n def __init__(self, table: Entity, data: dict[ColumnT, ColumnT.type.decoded_type]):\n \"\"\"\n :param table: The table this query is associated with\n :param data: A mapping of the column and corresponding data to set in the given table\n \"\"\"\n\n super().__init__(table.database)\n self.table = table\n self.data = data.items()\n self.where_statement = None\n\n def where(self, where: Where) -> Set:\n \"\"\"\n A method to attach WHERE clauses onto the SET statement\n\n :param where: The WHERE clause to add to the statement\n :return: A mutated version of this statement with the extended WHERE clause\n \"\"\"\n\n if self.where_statement is None:\n where.register(self)\n self.where_statement = where\n else:\n self.where_statement &= where\n return self\n\n def build_sql(self) -> str:\n set_section = \", \".join(f\"{column.name} = {self.parameter(column.type.encode(value))}\"\n for column, value in self.data)\n where_section = \"\" if self.where_statement is None else f\"\\nWHERE {self.where_statement}\"\n return f\"UPDATE {self.table}\\nSET {set_section}{where_section};\"\n", + "source": "\"\"\"\nThe module containing logic for SET statements.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import TypeVar, TYPE_CHECKING\nfrom .statement import Statement\nfrom ..where import Where\nif TYPE_CHECKING:\n from ..entity import Column, Entity\n ColumnT = TypeVar(\"ColumnT\", bound=Column)\n\n\nclass Set(Statement):\n \"\"\"\n The class containing the logic for building and executing SET statements with SQLiteFrame.\n \"\"\"\n\n def __init__(self, table: Entity, data: dict[ColumnT, ColumnT.type.decoded_type]):\n \"\"\"\n :param table: The table this query is associated with\n :param data: A mapping of the column and corresponding data to set in the given table\n \"\"\"\n\n super().__init__(table.database)\n self.table = table\n self.data = data.items()\n self.where_statement = None\n\n def where(self, where: Where) -> Set:\n \"\"\"\n A method to attach WHERE clauses onto the SET statement\n\n :param where: The WHERE clause to add to the statement\n :return: A mutated version of this statement with the extended WHERE clause\n \"\"\"\n\n if self.where_statement is None:\n where.register(self)\n self.where_statement = where\n else:\n self.where_statement &= where\n return self\n\n def build_sql(self) -> str:\n set_section = \", \".join(f\"{column.name} = {self.parameter(column.type.encode(value))}\"\n for column, value in self.data)\n where_section = \"\" if self.where_statement is None else f\"\\nWHERE {self.where_statement}\"\n return f\"UPDATE {self.table}\\nSET {set_section}{where_section};\"\n", "shortDescription": "The module containing logic for SET statements.", "longDescription": null, "deprecations": [], @@ -3803,7 +3803,7 @@ export const project = parseProject({ "meta": { "searchCategory": "module", "name": "statement", - "source": "\"\"\"\nThe module containing logic for statements in SQLiteFrame.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import Callable, Literal\nfrom abc import ABC, abstractmethod\nfrom ..result import Result\nfrom ..parameterized import Parameterized\nif False:\n from ..entity import Column\n from ..database import Database\n\n\nclass Statement(ABC):\n \"\"\"\n The abstract base class defining how statements should be structured in SQLiteFrame.\n \"\"\"\n\n def __init__(self, database: Database, yield_column_factory: Callable[[], list[Column]] = lambda: [],\n indeterminate_yield: bool = False):\n \"\"\"\n :param database: The database this statement is associated with\n :param yield_column_factory: A factory method to get the columns this statement will return data for\n :param indeterminate_yield: Whether columns cannot be assigned to the result of the statement\n \"\"\"\n self.database = database\n self.yield_column_factory = yield_column_factory\n self.indeterminate_yield = indeterminate_yield\n self.parameters = []\n self.parameterizeds = []\n\n def __str__(self) -> str:\n \"\"\"\n The string representation for this statement, used when it is being executed.\n\n :return: The valid SQL string representing this statement\n \"\"\"\n\n return self.build_sql()\n\n @property\n def query_parameters(self) -> list[object]:\n \"\"\"\n Gets the query parameters from this statement when executing the statement in a manner safe from SQL injection.\n\n This is involved in the usage of query parameters.\n\n :return: The query parameters from this statement\n \"\"\"\n\n return self.parameters + [parameter for extension in self.parameterizeds for parameter in extension.parameters]\n\n @abstractmethod\n def build_sql(self) -> str:\n \"\"\"\n Builds a valid SQL string representing this statement, used when executing this statement.\n\n :return: The valid SQL string representing this statement\n \"\"\"\n\n return \"\"\n\n def execute(self) -> Result:\n \"\"\"\n Executes this statement, and returns a corresponding result.\n\n :return: A result object which handles all SQLiteFrame query results independently\n \"\"\"\n\n return Result(self.yield_column_factory(), self.database.execute(self), indeterminate=self.indeterminate_yield)\n\n def register_parameterized(self, parameterized: Parameterized) -> None:\n \"\"\"\n Registers the query parameters from any subclauses with the statement for execution in order.\n\n :param parameterized: The parameterized object, such as a WHERE clause\n \"\"\"\n\n self.parameterizeds.append(parameterized)\n\n def parameter(self, parameter: object) -> Literal[\"?\"]:\n \"\"\"\n Registers a query parameter for this statement, and replaces it with a literal \"?\" for direct use in queries.\n\n :param parameter: The parameter to register\n :return: A \"?\" string literal for drop-in replacement when building queries\n \"\"\"\n\n self.parameters.append(parameter)\n return \"?\"\n", + "source": "\"\"\"\nThe module containing logic for statements in SQLiteFrame.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import Callable, Literal, TYPE_CHECKING\nfrom abc import ABC, abstractmethod\nfrom ..result import Result\nfrom ..parameterized import Parameterized\nif TYPE_CHECKING:\n from ..entity import Column\n from ..database import Database\n\n\nclass Statement(ABC):\n \"\"\"\n The abstract base class defining how statements should be structured in SQLiteFrame.\n \"\"\"\n\n def __init__(self, database: Database, yield_column_factory: Callable[[], list[Column]] = lambda: [],\n indeterminate_yield: bool = False):\n \"\"\"\n :param database: The database this statement is associated with\n :param yield_column_factory: A factory method to get the columns this statement will return data for\n :param indeterminate_yield: Whether columns cannot be assigned to the result of the statement\n \"\"\"\n self.database = database\n self.yield_column_factory = yield_column_factory\n self.indeterminate_yield = indeterminate_yield\n self.parameters = []\n self.parameterizeds = []\n\n def __str__(self) -> str:\n \"\"\"\n The string representation for this statement, used when it is being executed.\n\n :return: The valid SQL string representing this statement\n \"\"\"\n\n return self.build_sql()\n\n @property\n def query_parameters(self) -> list[object]:\n \"\"\"\n Gets the query parameters from this statement when executing the statement in a manner safe from SQL injection.\n\n This is involved in the usage of query parameters.\n\n :return: The query parameters from this statement\n \"\"\"\n\n return self.parameters + [parameter for extension in self.parameterizeds for parameter in extension.parameters]\n\n @abstractmethod\n def build_sql(self) -> str:\n \"\"\"\n Builds a valid SQL string representing this statement, used when executing this statement.\n\n :return: The valid SQL string representing this statement\n \"\"\"\n\n return \"\"\n\n def execute(self) -> Result:\n \"\"\"\n Executes this statement, and returns a corresponding result.\n\n :return: A result object which handles all SQLiteFrame query results independently\n \"\"\"\n\n return Result(self.yield_column_factory(), self.database.execute(self), indeterminate=self.indeterminate_yield)\n\n def register_parameterized(self, parameterized: Parameterized) -> None:\n \"\"\"\n Registers the query parameters from any subclauses with the statement for execution in order.\n\n :param parameterized: The parameterized object, such as a WHERE clause\n \"\"\"\n\n self.parameterizeds.append(parameterized)\n\n def parameter(self, parameter: object) -> Literal[\"?\"]:\n \"\"\"\n Registers a query parameter for this statement, and replaces it with a literal \"?\" for direct use in queries.\n\n :param parameter: The parameter to register\n :return: A \"?\" string literal for drop-in replacement when building queries\n \"\"\"\n\n self.parameters.append(parameter)\n return \"?\"\n", "shortDescription": "The module containing logic for statements in SQLiteFrame.", "longDescription": null, "deprecations": [], @@ -3821,7 +3821,7 @@ export const project = parseProject({ "searchCategory": "class", "name": "Statement", "source": "class Statement(ABC):\n \"\"\"\n The abstract base class defining how statements should be structured in SQLiteFrame.\n \"\"\"\n\n def __init__(self, database: Database, yield_column_factory: Callable[[], list[Column]] = lambda: [],\n indeterminate_yield: bool = False):\n \"\"\"\n :param database: The database this statement is associated with\n :param yield_column_factory: A factory method to get the columns this statement will return data for\n :param indeterminate_yield: Whether columns cannot be assigned to the result of the statement\n \"\"\"\n self.database = database\n self.yield_column_factory = yield_column_factory\n self.indeterminate_yield = indeterminate_yield\n self.parameters = []\n self.parameterizeds = []\n\n def __str__(self) -> str:\n \"\"\"\n The string representation for this statement, used when it is being executed.\n\n :return: The valid SQL string representing this statement\n \"\"\"\n\n return self.build_sql()\n\n @property\n def query_parameters(self) -> list[object]:\n \"\"\"\n Gets the query parameters from this statement when executing the statement in a manner safe from SQL injection.\n\n This is involved in the usage of query parameters.\n\n :return: The query parameters from this statement\n \"\"\"\n\n return self.parameters + [parameter for extension in self.parameterizeds for parameter in extension.parameters]\n\n @abstractmethod\n def build_sql(self) -> str:\n \"\"\"\n Builds a valid SQL string representing this statement, used when executing this statement.\n\n :return: The valid SQL string representing this statement\n \"\"\"\n\n return \"\"\n\n def execute(self) -> Result:\n \"\"\"\n Executes this statement, and returns a corresponding result.\n\n :return: A result object which handles all SQLiteFrame query results independently\n \"\"\"\n\n return Result(self.yield_column_factory(), self.database.execute(self), indeterminate=self.indeterminate_yield)\n\n def register_parameterized(self, parameterized: Parameterized) -> None:\n \"\"\"\n Registers the query parameters from any subclauses with the statement for execution in order.\n\n :param parameterized: The parameterized object, such as a WHERE clause\n \"\"\"\n\n self.parameterizeds.append(parameterized)\n\n def parameter(self, parameter: object) -> Literal[\"?\"]:\n \"\"\"\n Registers a query parameter for this statement, and replaces it with a literal \"?\" for direct use in queries.\n\n :param parameter: The parameter to register\n :return: A \"?\" string literal for drop-in replacement when building queries\n \"\"\"\n\n self.parameters.append(parameter)\n return \"?\"\n", - "signature": "(database: 'Database', yield_column_factory: 'Callable[[], list[Column]]' = at 0x0000024C8BF65800>, indeterminate_yield: 'bool' = False)", + "signature": "(database: 'Database', yield_column_factory: 'Callable[[], list[Column]]' = at 0x000001BED455DC60>, indeterminate_yield: 'bool' = False)", "parameters": [ { "component": "Parameter", @@ -3851,7 +3851,7 @@ export const project = parseProject({ "name": "yield_column_factory", "description": "A factory method to get the columns this statement will return data for", "annotation": "Callable[[], list[Column]]", - "default": " at 0x0000024C8BF65800>", + "default": " at 0x000001BED455DC60>", "isOptional": true }, "children": {} @@ -8306,7 +8306,7 @@ export const project = parseProject({ "meta": { "searchCategory": "module", "name": "condition", - "source": "\"\"\"\nThe module containing the logic for creating individual conditions in a WHERE clause.\n\"\"\"\n\nfrom __future__ import annotations\nfrom .comparisons import Comparisons\nfrom .conjunctions import Conjunctions\nfrom ..parameterized import Parameterized\n\nif False:\n from ..entity import Column\n from .where import Where\n\n\nclass Condition(Parameterized):\n \"\"\"\n The class that defines all logic for simple conditions in WHERE clauses (e.g. Column1 == \"Some String\")\n \"\"\"\n\n def __init__(self, left: Column, comparator: Comparisons, right: Column | object):\n \"\"\"\n :param left: The left segment of the condition, which can only be a column\n :param comparator: The comparator (e.g. '==') that is used in the condition\n :param right: The right segment of the condition, which can be a column or some data\n \"\"\"\n self.left = left\n self.comparator = comparator\n self.right = right\n self._parameters = []\n\n @property\n def parameters(self) -> list[object]:\n return self._parameters\n\n def __bool__(self) -> bool:\n \"\"\"\n Conditions always evaluate to false, in order to be compatible with __contains__ checks.\n\n :return: Always false\n \"\"\"\n return False\n\n def __or__(self, other: object) -> Where:\n \"\"\"\n Combines this condition with another condition or WHERE statement using bitwise OR syntax.\n\n Whether the passed object is a Condition object and Where object is an implementation detail.\n\n :param other: The condition or where object to combine with\n :return: A where statement object with the relevant functionality combining the parameter with an OR comparator\n \"\"\"\n\n return self.combine(other, Conjunctions.OR)\n\n def __and__(self, other: object) -> Where:\n \"\"\"\n Combines this condition with another condition or WHERE statement using bitwise AND syntax.\n\n Whether the passed object is a Condition object and Where object is an implementation detail.\n\n :param other: The condition or where object to combine with\n :return: A where statement object with the relevant functionality combining the parameter with an AND comparator\n \"\"\"\n\n return self.combine(other, Conjunctions.AND)\n\n def combine(self, other: object, conjunction: Conjunctions) -> Where:\n \"\"\"\n An internal, generalized method to combine this condition with another, with any conjunction.\n\n :param other: The condition or where object to combine with\n :param conjunction: The conjunction to combine with\n :return: A where statement object with the relevant combined functionality\n \"\"\"\n\n from .where import Where\n if not (isinstance(other, Condition) or isinstance(other, Where)):\n raise TypeError(f\"Cannot join Condition with type '{type(other)}'\") from None\n return Where(self, conjunction.value, other)\n\n def build_sql(self) -> str:\n from ..entity import Column\n right = f\"{self.right.table}.{self.right.name}\" if isinstance(self.right, Column) else \\\n self.parameter(self.left.type.encode(self.right))\n return f\"{self.left.table}.{self.left.name} {self.comparator.value} {right}\"\n", + "source": "\"\"\"\nThe module containing the logic for creating individual conditions in a WHERE clause.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import TYPE_CHECKING\nfrom .comparisons import Comparisons\nfrom .conjunctions import Conjunctions\nfrom ..parameterized import Parameterized\nif TYPE_CHECKING:\n from ..entity import Column\n from .where import Where\n\n\nclass Condition(Parameterized):\n \"\"\"\n The class that defines all logic for simple conditions in WHERE clauses (e.g. Column1 == \"Some String\")\n \"\"\"\n\n def __init__(self, left: Column, comparator: Comparisons, right: Column | object):\n \"\"\"\n :param left: The left segment of the condition, which can only be a column\n :param comparator: The comparator (e.g. '==') that is used in the condition\n :param right: The right segment of the condition, which can be a column or some data\n \"\"\"\n self.left = left\n self.comparator = comparator\n self.right = right\n self._parameters = []\n\n @property\n def parameters(self) -> list[object]:\n return self._parameters\n\n def __bool__(self) -> bool:\n \"\"\"\n Conditions always evaluate to false, in order to be compatible with __contains__ checks.\n\n :return: Always false\n \"\"\"\n return False\n\n def __or__(self, other: object) -> Where:\n \"\"\"\n Combines this condition with another condition or WHERE statement using bitwise OR syntax.\n\n Whether the passed object is a Condition object and Where object is an implementation detail.\n\n :param other: The condition or where object to combine with\n :return: A where statement object with the relevant functionality combining the parameter with an OR comparator\n \"\"\"\n\n return self.combine(other, Conjunctions.OR)\n\n def __and__(self, other: object) -> Where:\n \"\"\"\n Combines this condition with another condition or WHERE statement using bitwise AND syntax.\n\n Whether the passed object is a Condition object and Where object is an implementation detail.\n\n :param other: The condition or where object to combine with\n :return: A where statement object with the relevant functionality combining the parameter with an AND comparator\n \"\"\"\n\n return self.combine(other, Conjunctions.AND)\n\n def combine(self, other: object, conjunction: Conjunctions) -> Where:\n \"\"\"\n An internal, generalized method to combine this condition with another, with any conjunction.\n\n :param other: The condition or where object to combine with\n :param conjunction: The conjunction to combine with\n :return: A where statement object with the relevant combined functionality\n \"\"\"\n\n from .where import Where\n if not (isinstance(other, Condition) or isinstance(other, Where)):\n raise TypeError(f\"Cannot join Condition with type '{type(other)}'\") from None\n return Where(self, conjunction.value, other)\n\n def build_sql(self) -> str:\n from ..entity import Column\n right = f\"{self.right.table}.{self.right.name}\" if isinstance(self.right, Column) else \\\n self.parameter(self.left.type.encode(self.right))\n return f\"{self.left.table}.{self.left.name} {self.comparator.value} {right}\"\n", "shortDescription": "The module containing the logic for creating individual conditions in a WHERE clause.", "longDescription": null, "deprecations": [], @@ -8631,7 +8631,7 @@ export const project = parseProject({ "meta": { "searchCategory": "module", "name": "where", - "source": "\"\"\"\nThe module containing the logic involved in building WHERE clauses in complex queries.\n\"\"\"\n\nfrom __future__ import annotations\nfrom .conjunctions import Conjunctions\nfrom ..parameterized import Parameterized\n\nif False:\n from .condition import Condition\n\n\nclass Where(Parameterized):\n \"\"\"\n The class containing all the logic for WHERE clauses in complex queries.\n \"\"\"\n\n def __init__(self, *syntax: Condition | Conjunctions):\n \"\"\"\n :param syntax: The ordered conditions and conjunctions involved in the WHERE clause\n \"\"\"\n\n self.syntax = [\"(\", *syntax, \")\"]\n\n @property\n def parameters(self) -> list[object]:\n from .condition import Condition\n return [condition for parameters in map(lambda condition: condition.parameters, filter(\n lambda syntax: isinstance(syntax, Condition), self.syntax)) for condition in parameters]\n\n def build_sql(self) -> str:\n syntax = map(lambda part: part.value if isinstance(part, Conjunctions) else str(part), self.syntax)\n return \" \".join(syntax).replace(\"( \", \"(\").replace(\" )\", \")\")\n\n def __or__(self, other: Where | Condition) -> Where:\n \"\"\"\n Combines this WHERE statement with another condition or WHERE statement using bitwise OR syntax.\n\n Whether the passed object is a Condition object and Where object is an implementation detail.\n\n :param other: The condition or where object to combine with\n :return: A where statement object with the relevant functionality combining the parameter with an OR comparator\n \"\"\"\n\n return self.combine(other, Conjunctions.OR)\n\n def __and__(self, other: Where | Condition) -> Where:\n \"\"\"\n Combines this WHERE statement with another condition or WHERE statement using bitwise AND syntax.\n\n Whether the passed object is a Condition object and Where object is an implementation detail.\n\n :param other: The condition or where object to combine with\n :return: A where statement object with the relevant functionality combining the parameter with an AND comparator\n \"\"\"\n\n return self.combine(other, Conjunctions.AND)\n\n def combine(self, other: Where | Condition, conjunction: Conjunctions) -> Where:\n \"\"\"\n An internal, generalized method to combine this WHERE clause via mutation, using any conjunction.\n\n :param other: The condition or where object to combine with\n :param conjunction: The conjunction to combine with\n :return: A where statement object with the relevant combined functionality\n \"\"\"\n\n from .condition import Condition\n if not (isinstance(other, Condition) or isinstance(other, Where)):\n raise TypeError(f\"Cannot join Condition with type '{type(other)}'\") from None\n self.syntax.insert(0, \"(\")\n self.syntax.append(\")\")\n self.syntax.append(conjunction.value)\n if isinstance(other, Condition):\n self.syntax.append(other)\n return self\n self.syntax += other.syntax\n return self\n", + "source": "\"\"\"\nThe module containing the logic involved in building WHERE clauses in complex queries.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import TYPE_CHECKING\nfrom .conjunctions import Conjunctions\nfrom ..parameterized import Parameterized\nif TYPE_CHECKING:\n from .condition import Condition\n\n\nclass Where(Parameterized):\n \"\"\"\n The class containing all the logic for WHERE clauses in complex queries.\n \"\"\"\n\n def __init__(self, *syntax: Condition | Conjunctions):\n \"\"\"\n :param syntax: The ordered conditions and conjunctions involved in the WHERE clause\n \"\"\"\n\n self.syntax = [\"(\", *syntax, \")\"]\n\n @property\n def parameters(self) -> list[object]:\n from .condition import Condition\n return [condition for parameters in map(lambda condition: condition.parameters, filter(\n lambda syntax: isinstance(syntax, Condition), self.syntax)) for condition in parameters]\n\n def build_sql(self) -> str:\n syntax = map(lambda part: part.value if isinstance(part, Conjunctions) else str(part), self.syntax)\n return \" \".join(syntax).replace(\"( \", \"(\").replace(\" )\", \")\")\n\n def __or__(self, other: Where | Condition) -> Where:\n \"\"\"\n Combines this WHERE statement with another condition or WHERE statement using bitwise OR syntax.\n\n Whether the passed object is a Condition object and Where object is an implementation detail.\n\n :param other: The condition or where object to combine with\n :return: A where statement object with the relevant functionality combining the parameter with an OR comparator\n \"\"\"\n\n return self.combine(other, Conjunctions.OR)\n\n def __and__(self, other: Where | Condition) -> Where:\n \"\"\"\n Combines this WHERE statement with another condition or WHERE statement using bitwise AND syntax.\n\n Whether the passed object is a Condition object and Where object is an implementation detail.\n\n :param other: The condition or where object to combine with\n :return: A where statement object with the relevant functionality combining the parameter with an AND comparator\n \"\"\"\n\n return self.combine(other, Conjunctions.AND)\n\n def combine(self, other: Where | Condition, conjunction: Conjunctions) -> Where:\n \"\"\"\n An internal, generalized method to combine this WHERE clause via mutation, using any conjunction.\n\n :param other: The condition or where object to combine with\n :param conjunction: The conjunction to combine with\n :return: A where statement object with the relevant combined functionality\n \"\"\"\n\n from .condition import Condition\n if not (isinstance(other, Condition) or isinstance(other, Where)):\n raise TypeError(f\"Cannot join Condition with type '{type(other)}'\") from None\n self.syntax.insert(0, \"(\")\n self.syntax.append(\")\")\n self.syntax.append(conjunction.value)\n if isinstance(other, Condition):\n self.syntax.append(other)\n return self\n self.syntax += other.syntax\n return self\n", "shortDescription": "The module containing the logic involved in building WHERE clauses in complex queries.", "longDescription": null, "deprecations": [], @@ -8950,7 +8950,7 @@ export const project = parseProject({ "meta": { "searchCategory": "module", "name": "database", - "source": "\"\"\"\nA module containing the logic behind database connections and execution.\n\"\"\"\n\nfrom typing import Optional, Generator\nfrom dataclasses import dataclass, field\nfrom contextlib import contextmanager\nfrom sqlite3 import connect, Cursor, Connection\nfrom .entity import Entity\nfrom .statements import Statement, Pragma\nfrom .pragma import PragmaStatements\nfrom .result import Result\n\n\n@dataclass(eq=True, slots=True)\nclass Database:\n \"\"\"\n A class representing entire SQLite databases, which may include many tables.\n\n This class is the main controller for interacting with SQLiteFrame, allowing users\n to create and connect to databases with a pure Python API, and execute statements.\n\n :param path: The path at which the SQLite database file should be saved\n :param output: Whether any statements executed in a connection to this database should be output in the console\n :param foreign_keys: Whether to enable foreign key relations in this database initially\n \"\"\"\n\n path: str\n output: bool = False\n foreign_keys: bool = True\n tables: set[Entity] = field(init=False, default_factory=set)\n db_connection: Optional[Connection] = field(init=False, default=None)\n cursor: Optional[Cursor] = field(init=False, default=None)\n connections: list[bool] = field(init=False, default_factory=list)\n\n def add_table(self, table: Entity) -> None:\n \"\"\"\n Registers a table with the database.\n\n :param table: The table to add to the database\n \"\"\"\n\n self.tables.add(table)\n\n @property\n def commit_mode(self) -> bool:\n \"\"\"\n Gets the currently selected commit mode for the database.\n\n :return: Whether automatic commits are currently enabled\n \"\"\"\n\n return self.connections[-1]\n\n @property\n def connected(self) -> bool:\n \"\"\"\n Determines whether the database has any active connections.\n\n :return: Whether there are any active connections to the database\n \"\"\"\n\n return bool(self.connections)\n\n @property\n def foreign_keys_enabled(self) -> bool:\n \"\"\"\n Checks whether foreign key relations are enabled for this database.\n\n :return: Whether foreign key relations are enabled\n :raise RuntimeError: If there is no active connection to the database\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(f\"Could not check FK status without a pre-established connection\") from None\n return bool(Pragma(self, PragmaStatements.FOREIGN_KEYS).execute())\n\n def enable_foreign_keys(self) -> Result:\n \"\"\"\n Enables foreign key relations for this database, by issuing PRAGMA statement.\n\n :return: The result from the executed PRAGMA statement\n :raise RuntimeError: If there is no active connection to the database\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(f\"Could not enable FKs without a pre-established connection\") from None\n return Result([], self.execute(Pragma(self, PragmaStatements.FOREIGN_KEYS, pragma_value=\"ON\")))\n\n def disable_foreign_keys(self) -> Result:\n \"\"\"\n Disables foreign key relations for this database, by issuing PRAGMA statement.\n\n :return: The result from the executed PRAGMA statement\n :raise RuntimeError: If there is no active connection to the database\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(f\"Could not disabled FKs without a pre-established connection\") from None\n return Result([], self.execute(Pragma(self, PragmaStatements.FOREIGN_KEYS, pragma_value=\"OFF\")))\n\n def connect(self, commit: bool = True) -> Connection:\n \"\"\"\n Connects to the database.\n\n If a connection is already active, a new one will not be created - however,\n the commit mode will still be updated.\n\n :param commit: Whether to commit to the database automatically when the connection is terminated\n :return: An internal SQLite Connection object representing the connection\n \"\"\"\n\n if self.connected:\n self.connections.append(commit)\n return self.db_connection\n self.db_connection = connect(self.path)\n self.connections.append(commit)\n self.cursor = self.db_connection.cursor()\n if self.foreign_keys:\n self.enable_foreign_keys()\n return self.db_connection\n\n def disconnect(self) -> None:\n \"\"\"\n Closes an active connection to the database.\n\n :raise RuntimeError: When no connection is already established and a disconnect is attempted\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(f\"Could not disconnect without a pre-established connection\") from None\n self.connections.pop()\n if not self.connected:\n self.db_connection.close()\n self.db_connection = None\n\n def commit(self) -> None:\n \"\"\"\n Commits any unsaved changes to the database.\n\n :raise RuntimeError: If there is no active connection to the database\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(\"Could not commit without first being connected\") from None\n self.db_connection.commit()\n\n @contextmanager\n def connection(self, commit: bool = True) -> Generator[Connection, None, None]:\n \"\"\"\n A context manager to open a connection for the duration of a defined with context block.\n\n :param commit: Whether to commit to the database automatically when the connection is terminated\n :return: The internally created SQLite Connection object\n \"\"\"\n self.connect(commit=commit)\n try:\n yield self.db_connection\n finally:\n if self.commit_mode:\n self.commit()\n self.disconnect()\n\n def execute(self, statement: Statement | str, query_parameters: Optional[list[object]] = None) -> Cursor:\n \"\"\"\n Executes an SQLite statement, with an active connection to the database.\n\n An SQL-injection-safe method which sanitizes query variables using SQLite's parameterized queries.\n Statements can be constructed via SQLiteFrame's Statement wrappers, or via a plain string containing\n a valid SQLite statement - this can be useful for testing, and quick / lightweight commands.\n\n :param statement: The statement to execute\n :param query_parameters: Any parameterized query parameters to add to the query for sanitization\n :return: The internally created SQLite Cursor object\n :raise RuntimeError: When no connection is already established and a disconnect is attempted\n \"\"\"\n\n to_execute = str(statement)\n if query_parameters is None:\n query_parameters = statement.query_parameters if isinstance(statement, Statement) else []\n if not self.connected:\n statement = statement if isinstance(statement, str) else f\"'{statement.__class__.__name__}' statement\"\n raise RuntimeError(\n f\"Could not execute {statement} without connection\") from None\n if self.output:\n print(statement)\n return self.cursor.execute(to_execute, query_parameters)\n", + "source": "\"\"\"\nA module containing the logic behind database connections and execution.\n\"\"\"\n\nfrom typing import Optional, Generator\nfrom dataclasses import dataclass, field\nfrom contextlib import contextmanager\nfrom sqlite3 import connect, Cursor, Connection\nfrom pathlib import Path\nfrom .entity import Entity\nfrom .statements import Statement, Pragma\nfrom .pragma import PragmaStatements\nfrom .result import Result\n\n\n@dataclass(eq=True, slots=True)\nclass Database:\n \"\"\"\n A class representing entire SQLite databases, which may include many tables.\n\n This class is the main controller for interacting with SQLiteFrame, allowing users\n to create and connect to databases with a pure Python API, and execute statements.\n\n :param path: The path at which the SQLite database file should be saved\n :param output: Whether any statements executed in a connection to this database should be output in the console\n :param foreign_keys: Whether to enable foreign key relations in this database initially\n \"\"\"\n\n path: Path\n output: bool = False\n foreign_keys: bool = True\n tables: set[Entity] = field(init=False, default_factory=set)\n db_connection: Optional[Connection] = field(init=False, default=None)\n cursor: Optional[Cursor] = field(init=False, default=None)\n connections: list[bool] = field(init=False, default_factory=list)\n\n def add_table(self, table: Entity) -> None:\n \"\"\"\n Registers a table with the database.\n\n :param table: The table to add to the database\n \"\"\"\n\n self.tables.add(table)\n\n @property\n def commit_mode(self) -> bool:\n \"\"\"\n Gets the currently selected commit mode for the database.\n\n :return: Whether automatic commits are currently enabled\n \"\"\"\n\n return self.connections[-1]\n\n @property\n def connected(self) -> bool:\n \"\"\"\n Determines whether the database has any active connections.\n\n :return: Whether there are any active connections to the database\n \"\"\"\n\n return bool(self.connections)\n\n @property\n def foreign_keys_enabled(self) -> bool:\n \"\"\"\n Checks whether foreign key relations are enabled for this database.\n\n :return: Whether foreign key relations are enabled\n :raise RuntimeError: If there is no active connection to the database\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(f\"Could not check FK status without a pre-established connection\") from None\n return bool(Pragma(self, PragmaStatements.FOREIGN_KEYS).execute())\n\n def enable_foreign_keys(self) -> Result:\n \"\"\"\n Enables foreign key relations for this database, by issuing PRAGMA statement.\n\n :return: The result from the executed PRAGMA statement\n :raise RuntimeError: If there is no active connection to the database\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(f\"Could not enable FKs without a pre-established connection\") from None\n return Result([], self.execute(Pragma(self, PragmaStatements.FOREIGN_KEYS, pragma_value=\"ON\")))\n\n def disable_foreign_keys(self) -> Result:\n \"\"\"\n Disables foreign key relations for this database, by issuing PRAGMA statement.\n\n :return: The result from the executed PRAGMA statement\n :raise RuntimeError: If there is no active connection to the database\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(f\"Could not disabled FKs without a pre-established connection\") from None\n return Result([], self.execute(Pragma(self, PragmaStatements.FOREIGN_KEYS, pragma_value=\"OFF\")))\n\n def connect(self, commit: bool = True) -> Connection:\n \"\"\"\n Connects to the database.\n\n If a connection is already active, a new one will not be created - however,\n the commit mode will still be updated.\n\n :param commit: Whether to commit to the database automatically when the connection is terminated\n :return: An internal SQLite Connection object representing the connection\n \"\"\"\n\n if self.connected:\n self.connections.append(commit)\n return self.db_connection\n self.db_connection = connect(str(self.path.resolve()))\n self.connections.append(commit)\n self.cursor = self.db_connection.cursor()\n if self.foreign_keys:\n self.enable_foreign_keys()\n return self.db_connection\n\n def disconnect(self) -> None:\n \"\"\"\n Closes an active connection to the database.\n\n :raise RuntimeError: When no connection is already established and a disconnect is attempted\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(f\"Could not disconnect without a pre-established connection\") from None\n self.connections.pop()\n if not self.connected:\n self.db_connection.close()\n self.db_connection = None\n\n def commit(self) -> None:\n \"\"\"\n Commits any unsaved changes to the database.\n\n :raise RuntimeError: If there is no active connection to the database\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(\"Could not commit without first being connected\") from None\n self.db_connection.commit()\n\n @contextmanager\n def connection(self, commit: bool = True) -> Generator[Connection, None, None]:\n \"\"\"\n A context manager to open a connection for the duration of a defined with context block.\n\n :param commit: Whether to commit to the database automatically when the connection is terminated\n :return: The internally created SQLite Connection object\n \"\"\"\n self.connect(commit=commit)\n try:\n yield self.db_connection\n finally:\n if self.commit_mode:\n self.commit()\n self.disconnect()\n\n def execute(self, statement: Statement | str, query_parameters: Optional[list[object]] = None) -> Cursor:\n \"\"\"\n Executes an SQLite statement, with an active connection to the database.\n\n An SQL-injection-safe method which sanitizes query variables using SQLite's parameterized queries.\n Statements can be constructed via SQLiteFrame's Statement wrappers, or via a plain string containing\n a valid SQLite statement - this can be useful for testing, and quick / lightweight commands.\n\n :param statement: The statement to execute\n :param query_parameters: Any parameterized query parameters to add to the query for sanitization\n :return: The internally created SQLite Cursor object\n :raise RuntimeError: When no connection is already established and a disconnect is attempted\n \"\"\"\n\n to_execute = str(statement)\n if query_parameters is None:\n query_parameters = statement.query_parameters if isinstance(statement, Statement) else []\n if not self.connected:\n statement = statement if isinstance(statement, str) else f\"'{statement.__class__.__name__}' statement\"\n raise RuntimeError(\n f\"Could not execute {statement} without connection\") from None\n if self.output:\n print(statement)\n return self.cursor.execute(to_execute, query_parameters)\n", "shortDescription": "A module containing the logic behind database connections and execution.", "longDescription": null, "deprecations": [], @@ -8967,8 +8967,8 @@ export const project = parseProject({ "meta": { "searchCategory": "class", "name": "Database", - "source": "@dataclass(eq=True, slots=True)\nclass Database:\n \"\"\"\n A class representing entire SQLite databases, which may include many tables.\n\n This class is the main controller for interacting with SQLiteFrame, allowing users\n to create and connect to databases with a pure Python API, and execute statements.\n\n :param path: The path at which the SQLite database file should be saved\n :param output: Whether any statements executed in a connection to this database should be output in the console\n :param foreign_keys: Whether to enable foreign key relations in this database initially\n \"\"\"\n\n path: str\n output: bool = False\n foreign_keys: bool = True\n tables: set[Entity] = field(init=False, default_factory=set)\n db_connection: Optional[Connection] = field(init=False, default=None)\n cursor: Optional[Cursor] = field(init=False, default=None)\n connections: list[bool] = field(init=False, default_factory=list)\n\n def add_table(self, table: Entity) -> None:\n \"\"\"\n Registers a table with the database.\n\n :param table: The table to add to the database\n \"\"\"\n\n self.tables.add(table)\n\n @property\n def commit_mode(self) -> bool:\n \"\"\"\n Gets the currently selected commit mode for the database.\n\n :return: Whether automatic commits are currently enabled\n \"\"\"\n\n return self.connections[-1]\n\n @property\n def connected(self) -> bool:\n \"\"\"\n Determines whether the database has any active connections.\n\n :return: Whether there are any active connections to the database\n \"\"\"\n\n return bool(self.connections)\n\n @property\n def foreign_keys_enabled(self) -> bool:\n \"\"\"\n Checks whether foreign key relations are enabled for this database.\n\n :return: Whether foreign key relations are enabled\n :raise RuntimeError: If there is no active connection to the database\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(f\"Could not check FK status without a pre-established connection\") from None\n return bool(Pragma(self, PragmaStatements.FOREIGN_KEYS).execute())\n\n def enable_foreign_keys(self) -> Result:\n \"\"\"\n Enables foreign key relations for this database, by issuing PRAGMA statement.\n\n :return: The result from the executed PRAGMA statement\n :raise RuntimeError: If there is no active connection to the database\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(f\"Could not enable FKs without a pre-established connection\") from None\n return Result([], self.execute(Pragma(self, PragmaStatements.FOREIGN_KEYS, pragma_value=\"ON\")))\n\n def disable_foreign_keys(self) -> Result:\n \"\"\"\n Disables foreign key relations for this database, by issuing PRAGMA statement.\n\n :return: The result from the executed PRAGMA statement\n :raise RuntimeError: If there is no active connection to the database\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(f\"Could not disabled FKs without a pre-established connection\") from None\n return Result([], self.execute(Pragma(self, PragmaStatements.FOREIGN_KEYS, pragma_value=\"OFF\")))\n\n def connect(self, commit: bool = True) -> Connection:\n \"\"\"\n Connects to the database.\n\n If a connection is already active, a new one will not be created - however,\n the commit mode will still be updated.\n\n :param commit: Whether to commit to the database automatically when the connection is terminated\n :return: An internal SQLite Connection object representing the connection\n \"\"\"\n\n if self.connected:\n self.connections.append(commit)\n return self.db_connection\n self.db_connection = connect(self.path)\n self.connections.append(commit)\n self.cursor = self.db_connection.cursor()\n if self.foreign_keys:\n self.enable_foreign_keys()\n return self.db_connection\n\n def disconnect(self) -> None:\n \"\"\"\n Closes an active connection to the database.\n\n :raise RuntimeError: When no connection is already established and a disconnect is attempted\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(f\"Could not disconnect without a pre-established connection\") from None\n self.connections.pop()\n if not self.connected:\n self.db_connection.close()\n self.db_connection = None\n\n def commit(self) -> None:\n \"\"\"\n Commits any unsaved changes to the database.\n\n :raise RuntimeError: If there is no active connection to the database\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(\"Could not commit without first being connected\") from None\n self.db_connection.commit()\n\n @contextmanager\n def connection(self, commit: bool = True) -> Generator[Connection, None, None]:\n \"\"\"\n A context manager to open a connection for the duration of a defined with context block.\n\n :param commit: Whether to commit to the database automatically when the connection is terminated\n :return: The internally created SQLite Connection object\n \"\"\"\n self.connect(commit=commit)\n try:\n yield self.db_connection\n finally:\n if self.commit_mode:\n self.commit()\n self.disconnect()\n\n def execute(self, statement: Statement | str, query_parameters: Optional[list[object]] = None) -> Cursor:\n \"\"\"\n Executes an SQLite statement, with an active connection to the database.\n\n An SQL-injection-safe method which sanitizes query variables using SQLite's parameterized queries.\n Statements can be constructed via SQLiteFrame's Statement wrappers, or via a plain string containing\n a valid SQLite statement - this can be useful for testing, and quick / lightweight commands.\n\n :param statement: The statement to execute\n :param query_parameters: Any parameterized query parameters to add to the query for sanitization\n :return: The internally created SQLite Cursor object\n :raise RuntimeError: When no connection is already established and a disconnect is attempted\n \"\"\"\n\n to_execute = str(statement)\n if query_parameters is None:\n query_parameters = statement.query_parameters if isinstance(statement, Statement) else []\n if not self.connected:\n statement = statement if isinstance(statement, str) else f\"'{statement.__class__.__name__}' statement\"\n raise RuntimeError(\n f\"Could not execute {statement} without connection\") from None\n if self.output:\n print(statement)\n return self.cursor.execute(to_execute, query_parameters)\n", - "signature": "(path: str, output: bool = False, foreign_keys: bool = True) -> None", + "source": "@dataclass(eq=True, slots=True)\nclass Database:\n \"\"\"\n A class representing entire SQLite databases, which may include many tables.\n\n This class is the main controller for interacting with SQLiteFrame, allowing users\n to create and connect to databases with a pure Python API, and execute statements.\n\n :param path: The path at which the SQLite database file should be saved\n :param output: Whether any statements executed in a connection to this database should be output in the console\n :param foreign_keys: Whether to enable foreign key relations in this database initially\n \"\"\"\n\n path: Path\n output: bool = False\n foreign_keys: bool = True\n tables: set[Entity] = field(init=False, default_factory=set)\n db_connection: Optional[Connection] = field(init=False, default=None)\n cursor: Optional[Cursor] = field(init=False, default=None)\n connections: list[bool] = field(init=False, default_factory=list)\n\n def add_table(self, table: Entity) -> None:\n \"\"\"\n Registers a table with the database.\n\n :param table: The table to add to the database\n \"\"\"\n\n self.tables.add(table)\n\n @property\n def commit_mode(self) -> bool:\n \"\"\"\n Gets the currently selected commit mode for the database.\n\n :return: Whether automatic commits are currently enabled\n \"\"\"\n\n return self.connections[-1]\n\n @property\n def connected(self) -> bool:\n \"\"\"\n Determines whether the database has any active connections.\n\n :return: Whether there are any active connections to the database\n \"\"\"\n\n return bool(self.connections)\n\n @property\n def foreign_keys_enabled(self) -> bool:\n \"\"\"\n Checks whether foreign key relations are enabled for this database.\n\n :return: Whether foreign key relations are enabled\n :raise RuntimeError: If there is no active connection to the database\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(f\"Could not check FK status without a pre-established connection\") from None\n return bool(Pragma(self, PragmaStatements.FOREIGN_KEYS).execute())\n\n def enable_foreign_keys(self) -> Result:\n \"\"\"\n Enables foreign key relations for this database, by issuing PRAGMA statement.\n\n :return: The result from the executed PRAGMA statement\n :raise RuntimeError: If there is no active connection to the database\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(f\"Could not enable FKs without a pre-established connection\") from None\n return Result([], self.execute(Pragma(self, PragmaStatements.FOREIGN_KEYS, pragma_value=\"ON\")))\n\n def disable_foreign_keys(self) -> Result:\n \"\"\"\n Disables foreign key relations for this database, by issuing PRAGMA statement.\n\n :return: The result from the executed PRAGMA statement\n :raise RuntimeError: If there is no active connection to the database\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(f\"Could not disabled FKs without a pre-established connection\") from None\n return Result([], self.execute(Pragma(self, PragmaStatements.FOREIGN_KEYS, pragma_value=\"OFF\")))\n\n def connect(self, commit: bool = True) -> Connection:\n \"\"\"\n Connects to the database.\n\n If a connection is already active, a new one will not be created - however,\n the commit mode will still be updated.\n\n :param commit: Whether to commit to the database automatically when the connection is terminated\n :return: An internal SQLite Connection object representing the connection\n \"\"\"\n\n if self.connected:\n self.connections.append(commit)\n return self.db_connection\n self.db_connection = connect(str(self.path.resolve()))\n self.connections.append(commit)\n self.cursor = self.db_connection.cursor()\n if self.foreign_keys:\n self.enable_foreign_keys()\n return self.db_connection\n\n def disconnect(self) -> None:\n \"\"\"\n Closes an active connection to the database.\n\n :raise RuntimeError: When no connection is already established and a disconnect is attempted\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(f\"Could not disconnect without a pre-established connection\") from None\n self.connections.pop()\n if not self.connected:\n self.db_connection.close()\n self.db_connection = None\n\n def commit(self) -> None:\n \"\"\"\n Commits any unsaved changes to the database.\n\n :raise RuntimeError: If there is no active connection to the database\n \"\"\"\n\n if not self.connected:\n raise RuntimeError(\"Could not commit without first being connected\") from None\n self.db_connection.commit()\n\n @contextmanager\n def connection(self, commit: bool = True) -> Generator[Connection, None, None]:\n \"\"\"\n A context manager to open a connection for the duration of a defined with context block.\n\n :param commit: Whether to commit to the database automatically when the connection is terminated\n :return: The internally created SQLite Connection object\n \"\"\"\n self.connect(commit=commit)\n try:\n yield self.db_connection\n finally:\n if self.commit_mode:\n self.commit()\n self.disconnect()\n\n def execute(self, statement: Statement | str, query_parameters: Optional[list[object]] = None) -> Cursor:\n \"\"\"\n Executes an SQLite statement, with an active connection to the database.\n\n An SQL-injection-safe method which sanitizes query variables using SQLite's parameterized queries.\n Statements can be constructed via SQLiteFrame's Statement wrappers, or via a plain string containing\n a valid SQLite statement - this can be useful for testing, and quick / lightweight commands.\n\n :param statement: The statement to execute\n :param query_parameters: Any parameterized query parameters to add to the query for sanitization\n :return: The internally created SQLite Cursor object\n :raise RuntimeError: When no connection is already established and a disconnect is attempted\n \"\"\"\n\n to_execute = str(statement)\n if query_parameters is None:\n query_parameters = statement.query_parameters if isinstance(statement, Statement) else []\n if not self.connected:\n statement = statement if isinstance(statement, str) else f\"'{statement.__class__.__name__}' statement\"\n raise RuntimeError(\n f\"Could not execute {statement} without connection\") from None\n if self.output:\n print(statement)\n return self.cursor.execute(to_execute, query_parameters)\n", + "signature": "(path: pathlib.Path, output: bool = False, foreign_keys: bool = True) -> None", "parameters": [ { "component": "Parameter", @@ -8986,7 +8986,7 @@ export const project = parseProject({ "meta": { "name": "path", "description": null, - "annotation": "str", + "annotation": "Path", "default": null, "isOptional": false }, @@ -9190,7 +9190,7 @@ export const project = parseProject({ "meta": { "searchCategory": "subroutine", "name": "connect", - "source": " def connect(self, commit: bool = True) -> Connection:\n \"\"\"\n Connects to the database.\n\n If a connection is already active, a new one will not be created - however,\n the commit mode will still be updated.\n\n :param commit: Whether to commit to the database automatically when the connection is terminated\n :return: An internal SQLite Connection object representing the connection\n \"\"\"\n\n if self.connected:\n self.connections.append(commit)\n return self.db_connection\n self.db_connection = connect(self.path)\n self.connections.append(commit)\n self.cursor = self.db_connection.cursor()\n if self.foreign_keys:\n self.enable_foreign_keys()\n return self.db_connection\n", + "source": " def connect(self, commit: bool = True) -> Connection:\n \"\"\"\n Connects to the database.\n\n If a connection is already active, a new one will not be created - however,\n the commit mode will still be updated.\n\n :param commit: Whether to commit to the database automatically when the connection is terminated\n :return: An internal SQLite Connection object representing the connection\n \"\"\"\n\n if self.connected:\n self.connections.append(commit)\n return self.db_connection\n self.db_connection = connect(str(self.path.resolve()))\n self.connections.append(commit)\n self.cursor = self.db_connection.cursor()\n if self.foreign_keys:\n self.enable_foreign_keys()\n return self.db_connection\n", "signature": "(self, commit: bool = True) -> sqlite3.Connection", "parameters": [ { diff --git a/sqliteframe/entity/column.py b/sqliteframe/entity/column.py index 7bd980b..3bb4be2 100644 --- a/sqliteframe/entity/column.py +++ b/sqliteframe/entity/column.py @@ -3,11 +3,12 @@ """ from __future__ import annotations +from typing import TYPE_CHECKING from dataclasses import dataclass, field from ..types import Type from ..where import Comparisons, Condition from ..foreign_key import ForeignKey -if False: +if TYPE_CHECKING: from .entity import Entity diff --git a/sqliteframe/entity/entity.py b/sqliteframe/entity/entity.py index c1d123f..fb68250 100644 --- a/sqliteframe/entity/entity.py +++ b/sqliteframe/entity/entity.py @@ -3,7 +3,7 @@ """ from __future__ import annotations -from typing import TypeVar, Literal, Iterable, Optional, Callable, Iterator +from typing import TypeVar, Literal, Iterable, Optional, Callable, Iterator, TYPE_CHECKING from pprint import pformat from inspect import getmembers, isroutine from .column import Column @@ -11,7 +11,7 @@ from ..statements import InsertInto, Set, CreateTable, Select, DeleteFrom, DropTable from ..wildcards import Wildcards from ..foreign_key import ForeignKey -if False: +if TYPE_CHECKING: from ..database import Database diff --git a/sqliteframe/foreign_key/foreign_key.py b/sqliteframe/foreign_key/foreign_key.py index 3e63115..8f48d0c 100644 --- a/sqliteframe/foreign_key/foreign_key.py +++ b/sqliteframe/foreign_key/foreign_key.py @@ -4,10 +4,10 @@ from __future__ import annotations from functools import cached_property -from typing import TypeVar, Optional, Callable +from typing import TypeVar, Optional, Callable, TYPE_CHECKING from .restraints import Restraints from ..types import Type -if False: +if TYPE_CHECKING: from ..entity import Entity, Column diff --git a/sqliteframe/join/join.py b/sqliteframe/join/join.py index 0a64b2c..02353e0 100644 --- a/sqliteframe/join/join.py +++ b/sqliteframe/join/join.py @@ -3,9 +3,10 @@ """ from __future__ import annotations +from typing import TYPE_CHECKING from .join_types import JoinTypes from ..where import Condition, Where -if False: +if TYPE_CHECKING: from sqliteframe.entity import Entity diff --git a/sqliteframe/order_by/order_by.py b/sqliteframe/order_by/order_by.py index 074cf31..f8c00f5 100644 --- a/sqliteframe/order_by/order_by.py +++ b/sqliteframe/order_by/order_by.py @@ -3,8 +3,9 @@ """ from __future__ import annotations +from typing import TYPE_CHECKING from .order_types import OrderTypes -if False: +if TYPE_CHECKING: from sqliteframe.entity import Column diff --git a/sqliteframe/parameterized/parameterized.py b/sqliteframe/parameterized/parameterized.py index c0652a8..6d1460c 100644 --- a/sqliteframe/parameterized/parameterized.py +++ b/sqliteframe/parameterized/parameterized.py @@ -4,9 +4,8 @@ from __future__ import annotations from abc import ABC, abstractmethod -from typing import Literal - -if False: +from typing import Literal, TYPE_CHECKING +if TYPE_CHECKING: from ..statements import Statement diff --git a/sqliteframe/result/result.py b/sqliteframe/result/result.py index fd4a531..8b42cb2 100644 --- a/sqliteframe/result/result.py +++ b/sqliteframe/result/result.py @@ -3,10 +3,9 @@ """ from __future__ import annotations -from typing import Iterator +from typing import Iterator, TypeVar, TYPE_CHECKING from sqlite3 import Cursor -if False: - from typing import TypeVar +if TYPE_CHECKING: from sqliteframe.entity import Column ColumnT = TypeVar("ColumnT", bound=Column) diff --git a/sqliteframe/statements/create_table.py b/sqliteframe/statements/create_table.py index 1b0a4c3..f7baf61 100644 --- a/sqliteframe/statements/create_table.py +++ b/sqliteframe/statements/create_table.py @@ -3,8 +3,9 @@ """ from __future__ import annotations +from typing import TYPE_CHECKING from .statement import Statement -if False: +if TYPE_CHECKING: from ..entity import Column, Entity diff --git a/sqliteframe/statements/delete_from.py b/sqliteframe/statements/delete_from.py index b4bed56..f258a75 100644 --- a/sqliteframe/statements/delete_from.py +++ b/sqliteframe/statements/delete_from.py @@ -3,9 +3,10 @@ """ from __future__ import annotations +from typing import TYPE_CHECKING from .statement import Statement from ..where import Where, Condition -if False: +if TYPE_CHECKING: from ..entity import Entity diff --git a/sqliteframe/statements/drop_table.py b/sqliteframe/statements/drop_table.py index 97cccf5..af1a878 100644 --- a/sqliteframe/statements/drop_table.py +++ b/sqliteframe/statements/drop_table.py @@ -3,8 +3,9 @@ """ from __future__ import annotations +from typing import TYPE_CHECKING from .statement import Statement -if False: +if TYPE_CHECKING: from ..entity import Entity diff --git a/sqliteframe/statements/insert_into.py b/sqliteframe/statements/insert_into.py index 56f0780..e82d3f4 100644 --- a/sqliteframe/statements/insert_into.py +++ b/sqliteframe/statements/insert_into.py @@ -3,9 +3,9 @@ """ from __future__ import annotations +from typing import TypeVar, TYPE_CHECKING from .statement import Statement -if False: - from typing import TypeVar +if TYPE_CHECKING: from ..entity import Column, Entity ColumnT = TypeVar("ColumnT", bound=Column) diff --git a/sqliteframe/statements/pragma.py b/sqliteframe/statements/pragma.py index f1956b0..a18aed4 100644 --- a/sqliteframe/statements/pragma.py +++ b/sqliteframe/statements/pragma.py @@ -3,10 +3,10 @@ """ from __future__ import annotations -from typing import Optional +from typing import Optional, TYPE_CHECKING from .statement import Statement from ..pragma import PragmaStatements, PragmaTypes -if False: +if TYPE_CHECKING: from ..database import Database diff --git a/sqliteframe/statements/select.py b/sqliteframe/statements/select.py index 2fcfb38..584922a 100644 --- a/sqliteframe/statements/select.py +++ b/sqliteframe/statements/select.py @@ -3,12 +3,13 @@ """ from __future__ import annotations +from typing import TYPE_CHECKING from .statement import Statement from ..wildcards import Wildcards from ..order_by import OrderBy, OrderTypes from ..where import Where, Condition from ..join import Join, JoinTypes -if False: +if TYPE_CHECKING: from ..entity import Column, Entity diff --git a/sqliteframe/statements/set.py b/sqliteframe/statements/set.py index e023d8f..ab564d4 100644 --- a/sqliteframe/statements/set.py +++ b/sqliteframe/statements/set.py @@ -3,10 +3,10 @@ """ from __future__ import annotations +from typing import TypeVar, TYPE_CHECKING from .statement import Statement from ..where import Where -if False: - from typing import TypeVar +if TYPE_CHECKING: from ..entity import Column, Entity ColumnT = TypeVar("ColumnT", bound=Column) diff --git a/sqliteframe/statements/statement.py b/sqliteframe/statements/statement.py index 6330d6f..26afb65 100644 --- a/sqliteframe/statements/statement.py +++ b/sqliteframe/statements/statement.py @@ -3,11 +3,11 @@ """ from __future__ import annotations -from typing import Callable, Literal +from typing import Callable, Literal, TYPE_CHECKING from abc import ABC, abstractmethod from ..result import Result from ..parameterized import Parameterized -if False: +if TYPE_CHECKING: from ..entity import Column from ..database import Database diff --git a/sqliteframe/where/condition.py b/sqliteframe/where/condition.py index a43527b..8e5b113 100644 --- a/sqliteframe/where/condition.py +++ b/sqliteframe/where/condition.py @@ -3,11 +3,11 @@ """ from __future__ import annotations +from typing import TYPE_CHECKING from .comparisons import Comparisons from .conjunctions import Conjunctions from ..parameterized import Parameterized - -if False: +if TYPE_CHECKING: from ..entity import Column from .where import Where diff --git a/sqliteframe/where/where.py b/sqliteframe/where/where.py index 7efb147..5db6667 100644 --- a/sqliteframe/where/where.py +++ b/sqliteframe/where/where.py @@ -3,10 +3,10 @@ """ from __future__ import annotations +from typing import TYPE_CHECKING from .conjunctions import Conjunctions from ..parameterized import Parameterized - -if False: +if TYPE_CHECKING: from .condition import Condition