sqliter-py 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

sqliter/model/model.py

@@ -2,30 +2,96 @@
 
 from __future__ import annotations
 
-from typing import Optional
+import re
+from typing import Any, Optional, TypeVar, Union, get_args, get_origin
 
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict
+
+T = TypeVar("T", bound="BaseDBModel")
 
 
 class BaseDBModel(BaseModel):
     """Custom base model for database models."""
 
+    model_config = ConfigDict(
+        extra="ignore",
+        populate_by_name=True,
+        validate_assignment=False,
+        from_attributes=True,
+    )
+
     class Meta:
         """Configure the base model with default options."""
 
-        create_id: bool = True  # Whether to create an auto-increment ID
-        primary_key: str = "id"  # Default primary key field
+        create_pk: bool = (
+            True  # Whether to create an auto-increment primary key
+        )
+        primary_key: str = "id"  # Default primary key name
         table_name: Optional[str] = (
             None  # Table name, defaults to class name if not set
         )
 
+    @classmethod
+    def model_validate_partial(cls: type[T], obj: dict[str, Any]) -> T:
+        """Validate a partial model object."""
+        converted_obj: dict[str, Any] = {}
+        for field_name, value in obj.items():
+            field = cls.model_fields[field_name]
+            field_type: Optional[type] = field.annotation
+            if (
+                field_type is None or value is None
+            ):  # Direct check for None values here
+                converted_obj[field_name] = None
+            else:
+                origin = get_origin(field_type)
+                if origin is Union:
+                    args = get_args(field_type)
+                    for arg in args:
+                        try:
+                            # Try converting the value to the type
+                            converted_obj[field_name] = arg(value)
+                            break
+                        except (ValueError, TypeError):
+                            pass
+                    else:
+                        converted_obj[field_name] = value
+                else:
+                    converted_obj[field_name] = field_type(value)
+
+        return cls.model_construct(**converted_obj)
+
     @classmethod
     def get_table_name(cls) -> str:
-        """Get the table name from the Meta, or default to the classname."""
+        """Get the table name from the Meta, or generate one.
+
+        Returns:
+            str: The table name, either specified in the Meta class or
+                generated by converting the class name to pluralized snake_case
+                and removing any 'Model' suffix.
+        """
         table_name: str | None = getattr(cls.Meta, "table_name", None)
         if table_name is not None:
             return table_name
-        return cls.__name__.lower()  # Default to class name in lowercase
+
+        # Get class name and remove 'Model' suffix if present
+        class_name = cls.__name__.removesuffix("Model")
+
+        # Convert to snake_case
+        snake_case_name = re.sub(r"(?<!^)(?=[A-Z])", "_", class_name).lower()
+
+        # Pluralize the table name
+        try:
+            import inflect
+
+            p = inflect.engine()
+            return p.plural(snake_case_name)
+        except ImportError:
+            # Fallback to simple pluralization by adding 's'
+            return (
+                snake_case_name
+                if snake_case_name.endswith("s")
+                else snake_case_name + "s"
+            )
 
     @classmethod
     def get_primary_key(cls) -> str:
@@ -33,6 +99,6 @@ class BaseDBModel(BaseModel):
         return getattr(cls.Meta, "primary_key", "id")
 
     @classmethod
-    def should_create_id(cls) -> bool:
+    def should_create_pk(cls) -> bool:
         """Check whether the model should create an auto-increment ID."""
-        return getattr(cls.Meta, "create_id", True)
+        return getattr(cls.Meta, "create_pk", True)

sqliter/query/query.py

@@ -3,7 +3,16 @@
 from __future__ import annotations
 
 import sqlite3
-from typing import TYPE_CHECKING, Any, Callable, Optional, Union
+import warnings
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+    Optional,
+    Union,
+    overload,
+)
 
 from typing_extensions import LiteralString, Self
 
@@ -30,8 +39,22 @@ FilterValue = Union[
 class QueryBuilder:
     """Functions to build and execute queries for a given model."""
 
-    def __init__(self, db: SqliterDB, model_class: type[BaseDBModel]) -> None:
-        """Initialize the query builder with the database, model class, etc."""
+    def __init__(
+        self,
+        db: SqliterDB,
+        model_class: type[BaseDBModel],
+        fields: Optional[list[str]] = None,
+    ) -> None:
+        """Initialize the query builder.
+
+        Pass the database, model class, and optional fields.
+
+        Args:
+            db: The SqliterDB instance.
+            model_class: The model class to query.
+            fields: Optional list of field names to select. If None, all fields
+                are selected.
+        """
         self.db = db
         self.model_class = model_class
         self.table_name = model_class.get_table_name()  # Use model_class method
@@ -39,6 +62,22 @@ class QueryBuilder:
         self._limit: Optional[int] = None
         self._offset: Optional[int] = None
         self._order_by: Optional[str] = None
+        self._fields: Optional[list[str]] = fields
+
+        if self._fields:
+            self._validate_fields()
+
+    def _validate_fields(self) -> None:
+        """Validate that the specified fields exist in the model."""
+        if self._fields is None:
+            return
+        valid_fields = set(self.model_class.model_fields.keys())
+        invalid_fields = set(self._fields) - valid_fields
+        if invalid_fields:
+            err_message = (
+                f"Invalid fields specified: {', '.join(invalid_fields)}"
+            )
+            raise ValueError(err_message)
 
     def filter(self, **conditions: str | float | None) -> QueryBuilder:
         """Add filter conditions to the query."""
@@ -53,6 +92,53 @@ class QueryBuilder:
 
         return self
 
+    def fields(self, fields: Optional[list[str]] = None) -> QueryBuilder:
+        """Select specific fields to return in the query."""
+        if fields:
+            self._fields = fields
+            self._validate_fields()
+        return self
+
+    def exclude(self, fields: Optional[list[str]] = None) -> QueryBuilder:
+        """Exclude specific fields from the query output."""
+        if fields:
+            all_fields = set(self.model_class.model_fields.keys())
+
+            # Check for invalid fields before subtraction
+            invalid_fields = set(fields) - all_fields
+            if invalid_fields:
+                err = (
+                    "Invalid fields specified for exclusion: "
+                    f"{', '.join(invalid_fields)}"
+                )
+                raise ValueError(err)
+
+            # Subtract the fields specified for exclusion
+            self._fields = list(all_fields - set(fields))
+
+            # Explicit check: raise an error if no fields remain
+            if not self._fields:
+                err = "Exclusion results in no fields being selected."
+                raise ValueError(err)
+
+            # Now validate the remaining fields to ensure they are all valid
+            self._validate_fields()
+
+        return self
+
+    def only(self, field: str) -> QueryBuilder:
+        """Return only the specified single field."""
+        all_fields = set(self.model_class.model_fields.keys())
+
+        # Validate that the field exists
+        if field not in all_fields:
+            err = f"Invalid field specified: {field}"
+            raise ValueError(err)
+
+        # Set self._fields to just the single field
+        self._fields = [field]
+        return self
+
     def _get_operator_handler(
         self, operator: str
     ) -> Callable[[str, Any, str], None]:
@@ -182,34 +268,61 @@ class QueryBuilder:
             self._limit = -1
         return self
 
-    def order(self, order_by_field: str, direction: str = "ASC") -> Self:
-        """Order the results by a specific field and optionally direction.
-
-        Currently only supports ordering by a single field, though this will be
-        expanded in the future. You can chain this method to order by multiple
-        fields.
+    def order(
+        self,
+        order_by_field: str,
+        direction: Optional[str] = None,
+        *,
+        reverse: bool = False,
+    ) -> Self:
+        """Order the query results by the specified field.
 
-        Parameters:
+        Args:
             order_by_field (str): The field to order by.
-            direction (str, optional): The sorting direction, either 'ASC' or
-                'DESC'. Defaults to 'ASC'.
-
-        Returns:
-            Self: Returns the query object for chaining.
+            direction (Optional[str]): The ordering direction ('ASC' or 'DESC').
+                This is deprecated in favor of 'reverse'.
+            reverse (bool): Whether to reverse the order (True for descending,
+                False for ascending).
 
         Raises:
-            InvalidOrderError: If the field or direction is invalid.
+            InvalidOrderError: If the field doesn't exist in the model fields
+                or if both 'direction' and 'reverse' are specified.
+
+        Returns:
+            QueryBuilder: The current query builder instance with updated
+                ordering.
         """
+        if direction:
+            warnings.warn(
+                "'direction' argument is deprecated and will be removed in a "
+                "future version. Use 'reverse' instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
         if order_by_field not in self.model_class.model_fields:
             err = f"'{order_by_field}' does not exist in the model fields."
             raise InvalidOrderError(err)
-
-        valid_directions = {"ASC", "DESC"}
-        if direction.upper() not in valid_directions:
-            err = f"'{direction}' is not a valid sorting direction."
+        # Raise an exception if both 'direction' and 'reverse' are specified
+        if direction and reverse:
+            err = (
+                "Cannot specify both 'direction' and 'reverse' as it "
+                "is ambiguous."
+            )
             raise InvalidOrderError(err)
 
-        self._order_by = f'"{order_by_field}" {direction.upper()}'
+        # Determine the sorting direction
+        if reverse:
+            sort_order = "DESC"
+        elif direction:
+            sort_order = direction.upper()
+            if sort_order not in {"ASC", "DESC"}:
+                err = f"'{direction}' is not a valid sorting direction."
+                raise InvalidOrderError(err)
+        else:
+            sort_order = "ASC"
+
+        self._order_by = f'"{order_by_field}" {sort_order}'
         return self
 
     def _execute_query(
@@ -219,15 +332,20 @@ class QueryBuilder:
         count_only: bool = False,
     ) -> list[tuple[Any, ...]] | Optional[tuple[Any, ...]]:
         """Helper function to execute the query with filters."""
-        fields = ", ".join(self.model_class.model_fields)
+        if count_only:
+            fields = "COUNT(*)"
+        elif self._fields:
+            fields = ", ".join(f'"{field}"' for field in self._fields)
+        else:
+            fields = ", ".join(
+                f'"{field}"' for field in self.model_class.model_fields
+            )
+
+        sql = f'SELECT {fields} FROM "{self.table_name}"'  # noqa: S608 # nosec
 
         # Build the WHERE clause with special handling for None (NULL in SQL)
         values, where_clause = self._parse_filter()
 
-        select_fields = fields if not count_only else "COUNT(*)"
-
-        sql = f'SELECT {select_fields} FROM "{self.table_name}"'  # noqa: S608 # nosec
-
         if self.filters:
             sql += f" WHERE {where_clause}"
 
@@ -269,61 +387,68 @@ class QueryBuilder:
         where_clause = " AND ".join(where_clauses)
         return values, where_clause
 
-    def fetch_all(self) -> list[BaseDBModel]:
-        """Fetch all results matching the filters."""
-        results = self._execute_query()
-
-        if not results:
-            return []
-
-        return [
-            self.model_class(
-                **{
-                    field: row[idx]
-                    for idx, field in enumerate(self.model_class.model_fields)
-                }
+    def _convert_row_to_model(self, row: tuple[Any, ...]) -> BaseDBModel:
+        """Convert a result row tuple into a Pydantic model."""
+        if self._fields:
+            return self.model_class.model_validate_partial(
+                {field: row[idx] for idx, field in enumerate(self._fields)}
             )
-            for row in results
-        ]
-
-    def fetch_one(self) -> BaseDBModel | None:
-        """Fetch exactly one result."""
-        result = self._execute_query(fetch_one=True)
-        if not result:
-            return None
         return self.model_class(
             **{
-                field: result[idx]
+                field: row[idx]
                 for idx, field in enumerate(self.model_class.model_fields)
             }
         )
 
-    def fetch_first(self) -> BaseDBModel | None:
+    @overload
+    def _fetch_result(
+        self, *, fetch_one: Literal[True]
+    ) -> Optional[BaseDBModel]: ...
+
+    @overload
+    def _fetch_result(
+        self, *, fetch_one: Literal[False]
+    ) -> list[BaseDBModel]: ...
+
+    def _fetch_result(
+        self, *, fetch_one: bool = False
+    ) -> Union[list[BaseDBModel], Optional[BaseDBModel]]:
+        """Fetch one or all results and convert them to Pydantic models."""
+        result = self._execute_query(fetch_one=fetch_one)
+
+        if not result:
+            if fetch_one:
+                return None
+            return []
+
+        if fetch_one:
+            # Ensure we pass a tuple, not a list, to _convert_row_to_model
+            if isinstance(result, list):
+                result = result[
+                    0
+                ]  # Get the first (and only) result if it's wrapped in a list.
+            return self._convert_row_to_model(result)
+
+        return [self._convert_row_to_model(row) for row in result]
+
+    def fetch_all(self) -> list[BaseDBModel]:
+        """Fetch all results matching the filters."""
+        return self._fetch_result(fetch_one=False)
+
+    def fetch_one(self) -> Optional[BaseDBModel]:
+        """Fetch exactly one result."""
+        return self._fetch_result(fetch_one=True)
+
+    def fetch_first(self) -> Optional[BaseDBModel]:
         """Fetch the first result of the query."""
         self._limit = 1
-        result = self._execute_query()
-        if not result:
-            return None
-        return self.model_class(
-            **{
-                field: result[0][idx]
-                for idx, field in enumerate(self.model_class.model_fields)
-            }
-        )
+        return self._fetch_result(fetch_one=True)
 
-    def fetch_last(self) -> BaseDBModel | None:
+    def fetch_last(self) -> Optional[BaseDBModel]:
         """Fetch the last result of the query (based on the insertion order)."""
         self._limit = 1
         self._order_by = "rowid DESC"
-        result = self._execute_query()
-        if not result:
-            return None
-        return self.model_class(
-            **{
-                field: result[0][idx]
-                for idx, field in enumerate(self.model_class.model_fields)
-            }
-        )
+        return self._fetch_result(fetch_one=True)
 
     def count(self) -> int:
         """Return the count of records matching the filters."""

sqliter/sqliter.py

@@ -27,9 +27,24 @@ if TYPE_CHECKING:  # pragma: no cover
 class SqliterDB:
     """Class to manage SQLite database interactions."""
 
-    def __init__(self, db_filename: str, *, auto_commit: bool = True) -> None:
+    def __init__(
+        self,
+        db_filename: Optional[str] = None,
+        *,
+        memory: bool = False,
+        auto_commit: bool = True,
+    ) -> None:
         """Initialize the class and options."""
-        self.db_filename = db_filename
+        if memory:
+            self.db_filename = ":memory:"
+        elif db_filename:
+            self.db_filename = db_filename
+        else:
+            err = (
+                "Database name must be provided if not using an in-memory "
+                "database."
+            )
+            raise ValueError(err)
         self.auto_commit = auto_commit
         self.conn: Optional[sqlite3.Connection] = None
 
@@ -58,13 +73,13 @@ class SqliterDB:
         """Create a table based on the Pydantic model."""
         table_name = model_class.get_table_name()
         primary_key = model_class.get_primary_key()
-        create_id = model_class.should_create_id()
+        create_pk = model_class.should_create_pk()
 
         fields = ", ".join(
             f"{field_name} TEXT" for field_name in model_class.model_fields
         )
 
-        if create_id:
+        if create_pk:
             create_table_sql = f"""
                 CREATE TABLE IF NOT EXISTS {table_name} (
                     {primary_key} INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -97,16 +112,17 @@ class SqliterDB:
         model_class = type(model_instance)
         table_name = model_class.get_table_name()
 
-        fields = ", ".join(model_class.model_fields)
-        placeholders = ", ".join(["?"] * len(model_class.model_fields))
-        values = tuple(
-            getattr(model_instance, field) for field in model_class.model_fields
+        data = model_instance.model_dump()
+        fields = ", ".join(data.keys())
+        placeholders = ", ".join(
+            ["?" if value is not None else "NULL" for value in data.values()]
         )
+        values = tuple(value for value in data.values() if value is not None)
 
         insert_sql = f"""
         INSERT INTO {table_name} ({fields})
         VALUES ({placeholders})
-    """  # noqa: S608
+        """  # noqa: S608
 
         try:
             with self.connect() as conn:
@@ -206,9 +222,32 @@ class SqliterDB:
         except sqlite3.Error as exc:
             raise RecordDeletionError(table_name) from exc
 
-    def select(self, model_class: type[BaseDBModel]) -> QueryBuilder:
-        """Start a query for the given model."""
-        return QueryBuilder(self, model_class)
+    def select(
+        self,
+        model_class: type[BaseDBModel],
+        fields: Optional[list[str]] = None,
+        exclude: Optional[list[str]] = None,
+    ) -> QueryBuilder:
+        """Start a query for the given model.
+
+        Args:
+            model_class: The model class to query.
+            fields: Optional list of field names to select. If None, all fields
+                are selected.
+            exclude: Optional list of field names to exclude from the query
+                output.
+
+        Returns:
+            QueryBuilder: An instance of QueryBuilder for the given model and
+            fields.
+        """
+        query_builder = QueryBuilder(self, model_class, fields)
+
+        # If exclude is provided, apply the exclude method
+        if exclude:
+            query_builder.exclude(exclude)
+
+        return query_builder
 
     # --- Context manager methods ---
     def __enter__(self) -> Self:

{sqliter_py-0.2.0.dist-info → sqliter_py-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sqliter-py
-Version: 0.2.0
+Version: 0.3.0
 Summary: Interact with SQLite databases using Python and Pydantic
 Project-URL: Pull Requests, https://github.com/seapagan/sqliter-py/pulls
 Project-URL: Bug Tracker, https://github.com/seapagan/sqliter-py/issues
@@ -8,6 +8,7 @@ Project-URL: Changelog, https://github.com/seapagan/sqliter-py/blob/main/CHANGEL
 Project-URL: Repository, https://github.com/seapagan/sqliter-py
 Author-email: Grant Ramsay <grant@gnramsay.com>
 License-Expression: MIT
+License-File: LICENSE.txt
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -21,6 +22,8 @@ Classifier: Topic :: Software Development
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
 Requires-Dist: pydantic>=2.9.0
+Provides-Extra: extras
+Requires-Dist: inflect==7.0.0; extra == 'extras'
 Description-Content-Type: text/markdown
 
 # SQLiter <!-- omit in toc -->
@@ -44,19 +47,28 @@ time).
 The ideal use case is more for Python CLI tools that need to store data in a
 database-like format without needing to learn SQL or use a full ORM.
 
-> [!NOTE]
+> [!IMPORTANT]
 > This project is still in the early stages of development and is lacking some
 > planned functionality. Please use with caution.
 >
+> Also, structures like `list`, `dict`, `set` etc are not supported **at this
+> time** as field types, since SQLite does not have a native column type for
+> these. I will look at implementing these in the future, probably by
+> serializing them to JSON or pickling them and storing in a text field. For
+> now, you can actually do this manually when creating your Model (use `TEXT` or
+> `BLOB` fields), then serialize before saving after and retrieving data.
+>
 > See the [TODO](TODO.md) for planned features and improvements.
 
 - [Features](#features)
 - [Installation](#installation)
+  - [Optional Dependencies](#optional-dependencies)
 - [Quick Start](#quick-start)
 - [Detailed Usage](#detailed-usage)
   - [Defining Models](#defining-models)
   - [Database Operations](#database-operations)
     - [Creating a Connection](#creating-a-connection)
+    - [Using an In-Memory Database](#using-an-in-memory-database)
     - [Creating Tables](#creating-tables)
     - [Inserting Records](#inserting-records)
     - [Querying Records](#querying-records)
@@ -65,6 +77,11 @@ database-like format without needing to learn SQL or use a full ORM.
     - [Commit your changes](#commit-your-changes)
     - [Close the Connection](#close-the-connection)
   - [Transactions](#transactions)
+  - [Ordering](#ordering)
+  - [Field Control](#field-control)
+    - [Selecting Specific Fields](#selecting-specific-fields)
+    - [Excluding Specific Fields](#excluding-specific-fields)
+    - [Returning exactly one explicit field only](#returning-exactly-one-explicit-field-only)
   - [Filter Options](#filter-options)
     - [Basic Filters](#basic-filters)
     - [Null Checks](#null-checks)
@@ -73,6 +90,7 @@ database-like format without needing to learn SQL or use a full ORM.
     - [String Operations (Case-Sensitive)](#string-operations-case-sensitive)
     - [String Operations (Case-Insensitive)](#string-operations-case-insensitive)
 - [Contributing](#contributing)
+- [Exceptions](#exceptions)
 - [License](#license)
 - [Acknowledgements](#acknowledgements)
 
@@ -83,29 +101,60 @@ database-like format without needing to learn SQL or use a full ORM.
 - Basic query building with filtering, ordering, and pagination
 - Transaction support
 - Custom exceptions for better error handling
+- Full type hinting and type checking
+- No external dependencies other than Pydantic
+- Full test coverage
 
 ## Installation
 
 You can install SQLiter using whichever method you prefer or is compatible with
 your project setup.
 
+With `uv` which is rapidly becoming my favorite tool for managing projects and
+virtual environments (`uv` is used for developing this project and in the CI):
+
+```bash
+uv add sqliter-py
+```
+
 With `pip`:
 
 ```bash
 pip install sqliter-py
 ```
 
-Or `Poetry`:
+Or with `Poetry`:
 
 ```bash
 poetry add sqliter-py
 ```
 
-Or `uv` which is rapidly becoming my favorite tool for managing projects and
-virtual environments (`uv` is used for developing this project and in the CI):
+### Optional Dependencies
+
+Currently by default, the only external dependency is Pydantic. However, there
+are some optional dependencies that can be installed to enable additional
+features:
+
+- `inflect`: For pluralizing table names (if not specified). This just offers a
+  more-advanced pluralization than the default method used. In most cases you
+  will not need this.
+
+These can be installed using `uv`:
 
 ```bash
-uv add sqliter-py
+uv add 'sqliter-py[extras]'
+```
+
+Or with `pip`:
+
+```bash
+pip install 'sqliter-py[extras]'
+```
+
+Or with `Poetry`:
+
+```bash
+poetry add 'sqliter-py[extras]'
 ```
 
 ## Quick Start
@@ -165,9 +214,28 @@ class User(BaseDBModel):
     class Meta:
         table_name = "users"
         primary_key = "name"  # Default is "id"
-        create_id = False  # Set to True to auto-create an ID field
+        create_pk = False  # disable auto-creating an incrementing primary key - default is True
 ```
 
+For a standard database with an auto-incrementing integer 'id' primary key, you
+do not need to specify the `primary_key` or `create_pk` fields. If you want to
+specify a different primary key field name, you can do so using the
+`primary_key` field in the `Meta` class.
+
+If `table_name` is not specified, the table name will be the same as the model
+name, converted to 'snake_case' and pluralized (e.g., `User` -> `users`). Also,
+any 'Model' suffix will be removed (e.g., `UserModel` -> `users`). To override
+this behavior, you can specify the `table_name` in the `Meta` class manually as
+above.
+
+> [!NOTE]
+>
+> The pluralization is pretty basic by default, and just consists of adding an
+> 's' if not already there. This will fail on words like 'person' or 'child'. If
+> you need more advanced pluralization, you can install the `extras` package as
+> mentioned above. Of course, you can always specify the `table_name` manually
+> in this case!
+
 ### Database Operations
 
 #### Creating a Connection
@@ -190,6 +258,36 @@ It is then up to you to manually commit changes using the `commit()` method.
 This can be useful when you want to perform multiple operations in a single
 transaction without the overhead of committing after each operation.
 
+#### Using an In-Memory Database
+
+If you want to use an in-memory database, you can set `memory=True` when
+creating the database connection:
+
+```python
+db = SqliterDB(memory=True)
+```
+
+This will create an in-memory database that is not persisted to disk. If you
+also specify a database name, it will be ignored.
+
+```python
+db = SqliterDB("ignored.db", memory=True)
+```
+
+The `ignored.db` file will not be created, and the database will be in-memory.
+If you do not specify a database name, and do NOT set `memory=True`, an
+exception will be raised.
+
+> [!NOTE]
+>
+> You can also use `":memory:"` as the database name (same as normal with
+> Sqlite) to create an in-memory database, this is just a cleaner and more
+> descriptive way to do it.
+>
+> ```python
+> db = SqliterDB(":memory:")
+> ```
+
 #### Creating Tables
 
 ```python
@@ -213,12 +311,17 @@ all_users = db.select(User).fetch_all()
 young_users = db.select(User).filter(age=25).fetch_all()
 
 # Order users
-ordered_users = db.select(User).order("age", direction="DESC").fetch_all()
+ordered_users = db.select(User).order("age", reverse=True).fetch_all()
 
 # Limit and offset
 paginated_users = db.select(User).limit(10).offset(20).fetch_all()
 ```
 
+> [!IMPORTANT]
+>
+> The `select()` MUST come first, before any filtering, ordering, or pagination
+> etc. This is the starting point for building your query.
+
 See below for more advanced filtering options.
 
 #### Updating Records
@@ -278,9 +381,83 @@ with db:
 > at the end (unless an exception occurs), regardless of the `auto_commit`
 > setting.
 >
-> the 'close()' method will also be called when the context manager exits, so you
+> the `close()` method will also be called when the context manager exits, so you
 > do not need to call it manually.
 
+### Ordering
+
+For now we only support ordering by the single field. You can specify the
+field to order by and whether to reverse the order:
+
+```python
+results = db.select(User).order("age", reverse=True).fetch_all()
+```
+
+This will order the results by the `age` field in descending order.
+
+> [!WARNING]
+>
+> Previously ordering was done using the `direction` parameter with `asc` or
+> `desc`, but this has been deprecated in favor of using the `reverse`
+> parameter. The `direction` parameter still works, but will raise a
+> `DeprecationWarning` and will be removed in a future release.
+
+### Field Control
+
+#### Selecting Specific Fields
+
+By default, all commands query and return all fields in the table. If you want
+to select only specific fields, you can pass them using the `fields()`
+method:
+
+```python
+results = db.select(User).fields(["name", "age"]).fetch_all()
+```
+
+This will return only the `name` and `age` fields for each record.
+
+You can also pass this as a parameter to the `select()` method:
+
+```python
+results = db.select(User, fields=["name", "age"]).fetch_all()
+```
+
+Note that using the `fields()` method will override any fields specified in the
+'select()' method.
+
+#### Excluding Specific Fields
+
+If you want to exclude specific fields from the results, you can use the
+`exclude()` method:
+
+```python
+results = db.select(User).exclude(["email"]).fetch_all()
+```
+
+This will return all fields except the `email` field.
+
+You can also pass this as a parameter to the `select()` method:
+
+```python
+results = db.select(User, exclude=["email"]).fetch_all()
+```
+
+#### Returning exactly one explicit field only
+
+If you only want to return a single field from the results, you can use the
+`only()` method:
+
+```python
+result = db.select(User).only("name").fetch_first()
+```
+
+This will return only the `name` field for the first record.
+
+This is exactly the same as using the `fields()` method with a single field, but
+very specific and obvious. **There is NO equivalent argument to this in the
+`select()` method**. An exception **WILL** be raised if you try to use this method
+with more than one field.
+
 ### Filter Options
 
 The `filter()` method in SQLiter supports various filter options to query records.
@@ -339,10 +516,83 @@ The `filter()` method in SQLiter supports various filter options to query record
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
+See the [CONTRIBUTING](CONTRIBUTING.md) guide for more information.
+
+Please note that this project is released with a Contributor Code of Conduct,
+which you can read in the [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) file.
+
+## Exceptions
+
+SQLiter includes several custom exceptions to handle specific errors that may occur during database operations. These exceptions inherit from a common base class, `SqliterError`, to ensure consistency across error messages and behavior.
+
+- **`SqliterError`**:
+  - The base class for all exceptions in SQLiter. It captures the exception context and chains any previous exceptions.
+  - **Message**: "An error occurred in the SQLiter package."
+
+- **`DatabaseConnectionError`**:
+  - Raised when the SQLite database connection fails.
+  - **Message**: "Failed to connect to the database: '{}'."
+
+- **`InvalidOffsetError`**:
+  - Raised when an invalid offset value (0 or negative) is used in queries.
+  - **Message**: "Invalid offset value: '{}'. Offset must be a positive integer."
+
+- **`InvalidOrderError`**:
+  - Raised when an invalid order value is used in queries, such as a non-existent field or an incorrect sorting direction.
+  - **Message**: "Invalid order value - {}"
+
+- **`TableCreationError`**:
+  - Raised when a table cannot be created in the database.
+  - **Message**: "Failed to create the table: '{}'."
+
+- **`RecordInsertionError`**:
+  - Raised when an error occurs during record insertion.
+  - **Message**: "Failed to insert record into table: '{}'."
+
+- **`RecordUpdateError`**:
+  - Raised when an error occurs during record update.
+  - **Message**: "Failed to update record in table: '{}'."
+
+- **`RecordNotFoundError`**:
+  - Raised when a record with the specified primary key is not found.
+  - **Message**: "Failed to find a record for key '{}'".
+
+- **`RecordFetchError`**:
+  - Raised when an error occurs while fetching records from the database.
+  - **Message**: "Failed to fetch record from table: '{}'."
+
+- **`RecordDeletionError`**:
+  - Raised when an error occurs during record deletion.
+  - **Message**: "Failed to delete record from table: '{}'."
+
+- **`InvalidFilterError`**:
+  - Raised when an invalid filter field is used in a query.
+  - **Message**: "Failed to apply filter: invalid field '{}'".
+
 ## License
 
 This project is licensed under the MIT License.
 
+Copyright (c) 2024 Grant Ramsay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.
+
 ## Acknowledgements
 
 SQLiter was initially developed as an experiment to see how helpful ChatGPT and

sqliter_py-0.3.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+sqliter/__init__.py,sha256=L8R0uvCbbbACwaI5xtd3khtvpNhlPRgHJAaYZvqjzig,134
+sqliter/constants.py,sha256=QEUC6kPkwYItgFRUmV6qfK9YV1PcUyUoBwj34yhAyik,441
+sqliter/exceptions.py,sha256=RP1T67PkJMOgkT7yIjES1xil832_UmuAeABtNiv-RKE,3756
+sqliter/sqliter.py,sha256=upUrUmHW6Us8AlIRB6EHDL3cEkjO-tbaRz6q1yGkxGo,8916
+sqliter/model/__init__.py,sha256=Ovpkbyx2-T6Oee0qFNgUBBc2M0uwK-cdG0pigG3mkd8,179
+sqliter/model/model.py,sha256=_-vJ6E38GN8Sxao-etqd6mu5Sy-zkBYsRhFVz5k_yjI,3516
+sqliter/query/__init__.py,sha256=BluNMJpuoo2PsYN-bL7fXlEc02O_8LgOMsvCmyv04ao,125
+sqliter/query/query.py,sha256=nsOKocZk7HZQgTckyae2RGpCPG4Y4wui7nTvqOk510Y,15851
+sqliter_py-0.3.0.dist-info/METADATA,sha256=2uDuEiSjE_2yNgt825liES8lnh5jKW9IjcAAY01KBMc,18890
+sqliter_py-0.3.0.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+sqliter_py-0.3.0.dist-info/licenses/LICENSE.txt,sha256=-r4mvgoEWzkl1hPO5k8I_iMwJate7zDj8p_Fmn7dhVg,1078
+sqliter_py-0.3.0.dist-info/RECORD,,

sqliter_py-0.3.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+Copyright (c) 2024 Grant Ramsay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.

sqliter_py-0.2.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-sqliter/__init__.py,sha256=L8R0uvCbbbACwaI5xtd3khtvpNhlPRgHJAaYZvqjzig,134
-sqliter/constants.py,sha256=QEUC6kPkwYItgFRUmV6qfK9YV1PcUyUoBwj34yhAyik,441
-sqliter/exceptions.py,sha256=RP1T67PkJMOgkT7yIjES1xil832_UmuAeABtNiv-RKE,3756
-sqliter/sqliter.py,sha256=1MOa763OQdwkiAHHAitEKox5O9EV0FVMbMWC7pqyk9U,7823
-sqliter/model/__init__.py,sha256=Ovpkbyx2-T6Oee0qFNgUBBc2M0uwK-cdG0pigG3mkd8,179
-sqliter/model/model.py,sha256=t1w38om37gma1gRk01Z_9II0h4g-l734ijN_8M1SYoY,1247
-sqliter/query/__init__.py,sha256=BluNMJpuoo2PsYN-bL7fXlEc02O_8LgOMsvCmyv04ao,125
-sqliter/query/query.py,sha256=dRW-Y7X3qH4HrTw-oFbomnl4Kz7WOsImIfoKXZqkMKQ,11648
-sqliter_py-0.2.0.dist-info/METADATA,sha256=OBYavQg-H3HipYh_mVkaJ4cL_EUpzqPk1MtypWUpwlg,9880
-sqliter_py-0.2.0.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
-sqliter_py-0.2.0.dist-info/RECORD,,