Merge pull request #48 from seapagan/add-properties

Author: seapagan

TODO.md

@@ -4,8 +4,6 @@
 
 - add (optional) `created_at` and `updated_at` fields to the BaseDBModel class
   which will be automatically updated when a record is created or updated.
-- add attributes to the BaseDBModel to read the table-name, file-name, is-memory
-  etc.
 - add an 'execute' method to the main class to allow executing arbitrary SQL
   queries which can be chained to the 'find_first' etc methods or just used
   directly.

docs/guide/connecting.md

@@ -65,3 +65,9 @@ db = SqliterDB("your_database.db", reset=True)
 
 This will effectively drop all user tables from the database. The file itself is
 not deleted, only the tables are dropped.
+
+## Database Properties
+
+The `SqliterDB` class provides several properties to access information about
+the database instance once it has been created. See the
+[Properties](properties.md) page (next) for more details.

docs/guide/properties.md

@@ -0,0 +1,107 @@
+
+# SqliterDB Properties
+
+## Overview
+
+The `SqliterDB` class includes several useful **read-only** properties that
+provide insight into the current state of the database. These properties allow
+users to easily query key database attributes, such as the filename, whether the
+database is in memory, auto-commit status, and the list of tables.
+
+### Properties
+
+1. **`filename`**
+   Returns the filename of the database, or `None` if the database is in-memory.
+
+   **Usage Example**:
+
+   ```python
+   db = SqliterDB(db_filename="test.db")
+   print(db.filename)  # Output: 'test.db'
+   ```
+
+2. **`is_memory`**
+   Returns `True` if the database is in-memory, otherwise `False`.
+
+   **Usage Example**:
+
+   ```python
+   db = SqliterDB(memory=True)
+   print(db.is_memory)  # Output: True
+   ```
+
+3. **`is_autocommit`**
+   Returns `True` if the database is in auto-commit mode, otherwise `False`.
+
+   **Usage Example**:
+
+   ```python
+   db = SqliterDB(auto_commit=True)
+   print(db.is_autocommit)  # Output: True
+   ```
+
+4. **`table_names`**
+   Returns a list of all user-defined table names in the database. The property temporarily reconnects if the connection is closed.
+
+   **Usage Example**:
+
+   ```python
+   db = SqliterDB(memory=True)
+   db.create_table(User)  # Assume 'User' is a predefined model
+   print(db.table_names)  # Output: ['user']
+   ```
+
+## Property Details
+
+### `filename`
+
+This property allows users to retrieve the current database filename. For in-memory databases, this property returns `None`, as no filename is associated with an in-memory database.
+
+- **Type**: `Optional[str]`
+- **Returns**: The database filename or `None` if in memory.
+
+### `is_memory`
+
+This property indicates whether the database is in memory. It simplifies the check for memory-based databases, returning `True` for in-memory and `False` otherwise.
+
+- **Type**: `bool`
+- **Returns**: `True` if the database is in memory, otherwise `False`.
+
+### `is_autocommit`
+
+This property returns whether the database is in auto-commit mode. If `auto_commit` is enabled, every operation is automatically committed without requiring an explicit `commit()` call.
+
+- **Type**: `bool`
+- **Returns**: `True` if auto-commit mode is enabled, otherwise `False`.
+
+### `table_names`
+
+This property retrieves a list of user-defined table names from the database. It does not include system tables (`sqlite_`). If the database connection is closed, this property will temporarily reconnect to query the table names and close the connection afterward.
+
+- **Type**: `list[str]`
+- **Returns**: A list of user-defined table names in the database.
+- **Raises**: `DatabaseConnectionError` if the database connection fails to re-establish.
+
+## Example
+
+Here's a complete example demonstrating the use of the new properties:
+
+```python
+from sqliter import SqliterDB
+from sqliter.model import BaseDBModel
+
+# Define a simple model
+class User(BaseDBModel):
+    id: int
+    name: str
+
+# Create an in-memory database
+db = SqliterDB(memory=True)
+db.create_table(User)
+
+# Access properties
+print(db.filename)        # Output: None
+print(db.is_memory)       # Output: True
+print(db.is_autocommit)   # Output: True (this is the default)
+print(db.table_names)     # Output: ['user']
+```

mkdocs.yml

@@ -72,6 +72,7 @@ nav:
       - Overview: guide/guide.md
       - Models: guide/models.md
       - Connect to a Database: guide/connecting.md
+      - Properties: guide/properties.md
       - Table Operations: guide/tables.md
       - Data Operations: guide/data-ops.md
       - Transactions: guide/transactions.md

sqliter/sqliter.py

@@ -51,6 +51,8 @@ class SqliterDB:
         logger (Optional[logging.Logger]): Custom logger for debug output.
     """
 
+    MEMORY_DB = ":memory:"
+
     def __init__(
         self,
         db_filename: Optional[str] = None,
@@ -76,7 +78,7 @@ def __init__(
             ValueError: If no filename is provided for a non-memory database.
         """
         if memory:
-            self.db_filename = ":memory:"
+            self.db_filename = self.MEMORY_DB
         elif db_filename:
             self.db_filename = db_filename
         else:
@@ -99,6 +101,54 @@ def __init__(
         if self.reset:
             self._reset_database()
 
+    @property
+    def filename(self) -> Optional[str]:
+        """Returns the filename of the current database or None if in-memory."""
+        return None if self.db_filename == self.MEMORY_DB else self.db_filename
+
+    @property
+    def is_memory(self) -> bool:
+        """Returns True if the database is in-memory."""
+        return self.db_filename == self.MEMORY_DB
+
+    @property
+    def is_autocommit(self) -> bool:
+        """Returns True if auto-commit is enabled."""
+        return self.auto_commit
+
+    @property
+    def is_connected(self) -> bool:
+        """Returns True if the database is connected, False otherwise."""
+        return self.conn is not None
+
+    @property
+    def table_names(self) -> list[str]:
+        """Returns a list of all table names in the database.
+
+        Temporarily connects to the database if not connected and restores
+        the connection state afterward.
+        """
+        was_connected = self.is_connected
+        if not was_connected:
+            self.connect()
+
+        if self.conn is None:
+            err_msg = "Failed to establish a database connection."
+            raise DatabaseConnectionError(err_msg)
+
+        cursor = self.conn.cursor()
+        cursor.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' "
+            "AND name NOT LIKE 'sqlite_%';"
+        )
+        tables = [row[0] for row in cursor.fetchall()]
+
+        # Restore the connection state
+        if not was_connected:
+            self.close()
+
+        return tables
+
     def _reset_database(self) -> None:
         """Drop all user-created tables in the database."""
         with self.connect() as conn:

tests/test_properties.py

@@ -0,0 +1,147 @@
+"""Test the read-only properties in the SqliterDB class."""
+
+import tempfile
+
+import pytest
+
+from sqliter.exceptions import DatabaseConnectionError
+from sqliter.model.model import BaseDBModel
+from sqliter.sqliter import SqliterDB
+
+
+class TestSqliterDBProperties:
+    """Test suite for the read-only properties in the SqliterDB class."""
+
+    def test_filename_property_memory_db(self) -> None:
+        """Test the 'filename' property for an in-memory database."""
+        db = SqliterDB(memory=True)
+        assert db.filename is None, "Expected None for in-memory database"
+
+    def test_filename_property_file_db(self) -> None:
+        """Test the 'filename' property for a file-based database."""
+        db = SqliterDB(db_filename="test.db")
+        assert db.filename == "test.db", "Expected 'test.db' as filename"
+
+    def test_is_memory_property_true(self) -> None:
+        """Test the 'is_memory' property returns True for in-memory database."""
+        db = SqliterDB(memory=True)
+        assert db.is_memory is True, "Expected True for in-memory database"
+
+    def test_is_memory_property_false(self) -> None:
+        """Test 'is_memory' property returns False for file-based database."""
+        db = SqliterDB(db_filename="test.db")
+        assert db.is_memory is False, "Expected False for file-based database"
+
+    def test_is_autocommit_property_true(self) -> None:
+        """Test 'is_autocommit' prop returns True when auto-commit enabled."""
+        db = SqliterDB(memory=True, auto_commit=True)
+        assert db.is_autocommit is True, "Expected True for auto-commit enabled"
+
+    def test_is_autocommit_property_false(self) -> None:
+        """Test 'is_autocommit' prop returns False when auto-commit disabled."""
+        db = SqliterDB(memory=True, auto_commit=False)
+        assert (
+            db.is_autocommit is False
+        ), "Expected False for auto-commit disabled"
+
+    def test_is_connected_property_when_connected(self) -> None:
+        """Test the 'is_connected' property when the database is connected."""
+        db = SqliterDB(memory=True)
+        with db.connect():
+            assert db.is_connected is True, "Expected True when connected"
+
+    def test_is_connected_property_when_disconnected(self) -> None:
+        """Test 'is_connected' property when the database is disconnected."""
+        db = SqliterDB(memory=True)
+        assert db.is_connected is False, "Expected False when not connected"
+
+    def test_table_names_property(self) -> None:
+        """Test the 'table_names' property returns correct tables."""
+
+        # Define a simple model for the test
+        class TestTableModel(BaseDBModel):
+            id: int
+
+            class Meta:
+                table_name = "test_table"
+
+        # Create the database without using the context manager
+        db = SqliterDB(memory=True)
+        db.create_table(TestTableModel)  # ORM-based table creation
+
+        # Verify that the table exists while the connection is still open
+        table_names = db.table_names
+        assert (
+            "test_table" in table_names
+        ), f"Expected 'test_table', got {table_names}"
+
+        # Explicitly close the connection afterwards
+        db.close()
+
+    def test_table_names_property_when_disconnected(self) -> None:
+        """Test the 'table_names' property with no active connection."""
+
+        # Define a simple model for the test
+        class AnotherTableModel(BaseDBModel):
+            id: int
+
+            class Meta:
+                table_name = "another_table"
+
+        # Create the database without the context manager
+        db = SqliterDB(memory=True)
+        db.create_table(AnotherTableModel)  # ORM-based table creation
+
+        # Check the table names while the connection is still open
+        table_names = db.table_names
+        assert (
+            "another_table" in table_names
+        ), f"Expected 'another_table', got {table_names}"
+
+        # Close the connection explicitly after the check
+        db.close()
+
+    def test_table_names_property_no_connection_error(self) -> None:
+        """Test the 'table_names' property reconnects after disconnection.
+
+        This test uses a real temp database file since sqlite3 seems to bypass
+        the 'pyfakefs' filesystem.
+        """
+        with tempfile.NamedTemporaryFile(suffix=".sqlite") as temp_db:
+            db_filename = temp_db.name
+
+            # Define a simple model for the test
+            class TestTableModel(BaseDBModel):
+                id: int
+
+                class Meta:
+                    table_name = "test_table"
+
+            # Create the database using the temporary file
+            db = SqliterDB(db_filename=db_filename)
+            db.create_table(TestTableModel)
+
+            # Close the connection
+            db.close()
+
+            # Ensure that accessing table_names does NOT raise an error Since
+            # it's file-based, the table should still exist after reconnecting
+            table_names = db.table_names
+            assert (
+                "test_table" in table_names
+            ), f"Expected 'test_table', got {table_names}"
+
+    def test_table_names_connection_failure(self, mocker) -> None:
+        """Test 'table_names' raises exception if the connection fails."""
+        # Create an instance of the database
+        db = SqliterDB(memory=True)
+
+        # Mock the connect method to simulate a failed connection
+        mocker.patch.object(db, "connect", return_value=None)
+
+        # Close any existing connection to ensure db.conn is None
+        db.close()
+
+        # Attempt to access table_names and expect DatabaseConnectionError
+        with pytest.raises(DatabaseConnectionError):
+            _ = db.table_names