pleasant-database 1.3.0__tar.gz

pleasant_database-1.3.0/LICENSE

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

pleasant_database-1.3.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: pleasant-database
+Version: 1.3.0
+Summary: package for handling local database files and data
+Author-email: Elias Rodkey <elias.rodkey@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: numpy
+Requires-Dist: sqlalchemy
+Requires-Dist: loggers
+Requires-Dist: pandas
+Dynamic: license-file

pleasant_database-1.3.0/README.md

@@ -0,0 +1,115 @@
+# local_db_handler
+
+this package is a modular python package that allows for easy
+creation, reading, editing, and deleting local database files
+
+## License
+
+[MIT](https://choosealicense.com/licenses/mit/)
+
+## Usage/Examples
+
+**Install Package**
+Ensure you have access to the github repository
+Run the command:
+    pip install git+<https://github.com/EliasRodkey/local_db.git>
+
+### Import Package
+
+```python
+From local_db_handler import DatabaseFile, DatabaseManager, BaseTable
+```
+
+### Set Up Table Object
+
+Use the BaseTable class to create a table object that will be connected to using the DatabaseManager
+
+```python
+class TableName(BaseTable):
+    """A table object"""
+    __tablename__ = "table_name"
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    name = Column(String(50), nullable=False)
+    age = Column(Integer)
+    email = Column(String(100), unique=True)
+```
+
+The attributes here represent column names in the table, additional funcionality can be added to avoid duplicate entries, for example:
+
+```python
+email = Column(String(100), unique=True)
+```
+
+This forces all emails to be unique in the table.
+Another option is to add a special hash row that would be unique to each entry:
+
+```python
+    import hashlib
+
+def generate_hash(row):
+    # Concatenate values of all relevant columns
+    data = f"{row["col1"]}_{row["col2"]}_{row["col3"]}"
+    return hashlib.sha256(data.encode()).hexdigest()
+
+df["unique_id"] = df.apply(generate_hash, axis=1)
+```
+
+Additionally the \_\_tableargs\_\_ can be updated to make a custom unique filter based on multiple columns to the class attributes:
+
+```python
+__table_args__ = (
+    UniqueConstraint("column1", "column2", name="unique_combo"),  # Combination must be unique
+)
+```
+
+### Creating the DataFile
+
+The DatabaseFile object represents the actual file of the database and is required to initialize a DatabaseManager object.
+
+```python
+file = DatabaseFile(db_name, directory="data/dbs")
+
+db_name: valid .db filename
+directory: relative path to database directory (default data//dbs)
+```
+
+DatabaseFile funcitons:
+
+```python
+file.create() # Creates a db file in the directory location
+file.move(target_directory) # Moves the db file to a new directory
+file.exists() # Returns boolean, if the file exists
+file.delete() # Deletes the actual db file
+```
+
+### Create DatabaseManager
+
+The DatabaseManager takes a file and table as arguments and allows for common database operations on that table
+
+```python
+manager = DatabaseManager(table_class: BaseTable, databasefile: DatabaseFile)
+```
+
+The DatabaseFile functions can be accessed through the DatabaseManager.file attribute
+Basic database funcitons:
+
+```python
+manager.add_item(entry: dictionary with columns matching the db table class)
+manager.add_multiple_items(entries: list of entries)
+manager.append_dataframe(df) # pandas DataFrame with columns that match the db table class
+
+manager.fetch_all(as_dataframe=True) # returns all table class instances in the table
+manager.fetch_item_by_id(id: int, as_dataframe=True) # returns an individual table class instance with data
+manager.fetch_items_by_attribute(**kwargs, as_dataframe=True) # allows filtering of table by kwargs
+manager.filter_items(filters: dict, use_or=False, as_dataframe=True) # allows filtering of database table and reading of filtered items
+manager.to_dataframe() -> Returns the entire database as a pandas DataFrame
+
+manager.update_item(item_id: int, **kwargs) # updates values kwargs of an item with a given ID
+manager.delete_item(item_id: int) # Deletes an item with the given item id
+manager.delete_items_by_attribute(**kwargs) # Deletes items in a database where column values match kwargs.
+manager.delete_items_by_filter(filters: dict, use_or=False) # Deletes items in a database where filters apply.
+manager.clear_table() # Deletes all items in the database table.
+
+manager.start_session() # initiates when instance initialized
+manager.end_session() # should be called before exiting program
+```

pleasant_database-1.3.0/pleasant_database/__init__.py

@@ -0,0 +1,43 @@
+#!python3
+"""
+local_db_handler
+
+This package contains modules related to local database connection / creation / deletion / editing / etc.
+
+Modules:
+    - database_connections.py
+    - database_file.py:
+    - database_manager.py:
+    - utils.py:
+"""
+# Metadata
+__version__ = "1.3.0"
+__author__ = "Elias Rodkey"
+
+# Package Level Constants
+import os
+DEFAULT_DB_DIRECTORY = os.path.join(os.getcwd(), "data", "dbs")
+LOG_DIRECTORY = os.path.join(os.getcwd(), "data", "logs")
+
+# Configure root logger
+from loggers import configure_logging
+handler_controller = configure_logging(log_directory=LOG_DIRECTORY)
+
+# Imports modules, functions, and classes for clean package interface
+from .base_table import BaseTable, DatabaseIntegrityError
+from .database_connections import create_engine_conn, create_session
+from .database_file import DatabaseFile
+from .database_manager import DatabaseManager
+from .utils import check_db_exists, is_db_file
+
+# Defines importable functions for package
+__all__ = [
+    "check_db_exists",
+    "is_db_file",
+    "create_engine_conn",
+    "create_session",
+    "DatabaseFile",
+    "DatabaseManager",
+    "BaseTable",
+    "DatabaseIntegrityError"
+]

pleasant_database-1.3.0/pleasant_database/base_table.py

@@ -0,0 +1,127 @@
+"""
+local_db.base_table.py
+This module defines a base table class using SQLAlchemy"s declarative base. 
+It provides a foundation for creating database models and includes utility 
+functions to retrieve column names and their corresponding types.
+
+Classes:
+    Base: The declarative base class for all database models.
+    BaseTable: An abstract base class for database tables with utility methods.
+"""
+
+# Standard library imports
+from datetime import datetime, date, time, timedelta
+from decimal import Decimal
+from enum import Enum
+import re
+from typing import Any
+import uuid
+
+from sqlalchemy.orm import declarative_base
+from sqlalchemy import (
+    Column,  # Defines a column in a table
+    UniqueConstraint, # Ensures unique values in specified columns
+    Integer,  # Integer type
+    String,  # String type with optional length
+    Float,  # Floating-point number
+    Boolean,  # Boolean type (True/False)
+    Date,  # Date type (year, month, day)
+    DateTime,  # Date and time type
+    Time,  # Time type (hour, minute, second)
+    Text,  # Large text field
+    LargeBinary,  # Binary data (e.g., files, images)
+    JSON,  # JSON-encoded data
+    Enum,  # Enumerated type with fixed values
+    Numeric,  # Fixed-precision number
+    SmallInteger,  # Smaller integer type
+    BigInteger,  # Larger integer type
+    Interval,  # Time interval
+    Unicode,  # Unicode string
+    UnicodeText,  # Large Unicode text field
+    PickleType,  # Stores Python objects serialized via pickle
+    UUID,  # Universally unique identifier
+    ARRAY,  # Array type (PostgreSQL-specific)
+)
+
+SQLA_TYPE_MAP = {
+    Integer: int,
+    String: str,
+    Float: float,
+    Boolean: bool,
+    Date: date,
+    DateTime: datetime,
+    Time: time,
+    Text: str,
+    LargeBinary: bytes,
+    JSON: dict,
+    Enum: Enum,
+    Numeric: Decimal,
+    SmallInteger: int,
+    BigInteger: int,
+    Interval: timedelta,
+    Unicode: str,
+    UnicodeText: str,
+    PickleType: Any,
+    UUID: uuid.UUID,
+    ARRAY: list,
+}
+
+Base = declarative_base()
+
+
+
+class BaseTable(Base):
+    """
+    Abstract base class for database tables.
+    
+    properties:
+        - column_names: Returns a list of column names for the model.
+        - column_types: Returns a dictionary mapping column names to their types.
+    """
+    __abstract__ = True  # Prevents SQLAlchemy from creating a table for this class
+
+    @classmethod
+    def get_column_names(cls):
+        """Returns a list of column names for the model."""
+        return [column.name for column in cls.__table__.columns]
+
+
+    @classmethod
+    def get_column_sqla_types(cls):
+        """Returns a dictionary mapping column names to their types."""
+        return {column.name: type(column.type) for column in cls.__table__.columns}
+    
+    @classmethod
+    def get_column_python_types(cls):
+        """Returns a dictionary mapping column names to their types."""
+        return {column.name: SQLA_TYPE_MAP[type(column.type)] for column in cls.__table__.columns}
+    
+    @property
+    def column_names(self):
+        """Returns a list of column names for the instance."""
+        return self.get_column_names()
+
+    @property
+    def column_types(self):
+        """Returns a dictionary mapping column names to their types for the instance."""
+        return self.get_column_sqla_types()
+
+
+
+class DatabaseIntegrityError(Exception):
+    def __init__(self, orig: Exception, table: "BaseTable"):
+        self.table_name = table.__tablename__
+        self.message = str(orig.orig)
+        match = re.search(r"UNIQUE constraint failed: \w+\.(\w+)", self.message)
+        self.column = match.group(1) if match else None
+        detail = f", column: {self.column}" if self.column else ""
+        super().__init__(f"Database integrity error in {self.table_name}{detail}. {self.message}")
+
+
+
+class ItemNotFoundError(Exception):
+    def __init__(self, item_id, table: BaseTable, message: str="Item not found in database:"):
+        self.item_id = item_id
+        self.table_name = table.__tablename__
+        self.message = f"{message} {self.table_name}, id: {item_id}"
+        super().__init__(self.message)

pleasant_database-1.3.0/pleasant_database/database_connections.py

@@ -0,0 +1,57 @@
+#!python3
+"""
+local_db.database_connections.py
+
+This module contains functions which allow for connections to existing local database files
+
+Functions:
+    - create_engine_conn: creates a SQLalchemy engine object
+    - create_session: creates and returns a SQLalchemy Session class object
+"""
+
+# Third-Party library imports
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+# Local Imports
+from pleasant_database import DEFAULT_DB_DIRECTORY
+from pleasant_database.utils import LoggingExtras
+
+# Initialize module logger
+import logging
+logger = logging.getLogger(__name__)
+
+
+# Functions
+def create_engine_conn(relative_db_path:str=DEFAULT_DB_DIRECTORY) -> object:
+    """
+    Create and returns an SQLalchemy engine from a given db URL string
+
+    Args:
+        relative_db_path (str): the relative path to the database file, must be a valid .db filename
+    
+    Returns:
+        engine: a SQLalchemy engine object which can be used to connect to the database
+    """
+
+    logger.info(f"Creating connection engine to {relative_db_path}...", extra={
+                                                                        LoggingExtras.FILE: relative_db_path
+                                                                    })
+
+    return create_engine(f"sqlite:///{relative_db_path}")
+
+
+def create_session(engine):
+    """
+    Create and return a SQLalchemy session
+    
+    Args:
+        engine: a SQLalchemy engine object which can be used to connect to the database
+    
+    Returns:
+        Session: a SQLalchemy session object which can be used to interact with the database
+    """
+    logger.info(f"Creating session for {engine}...")
+    
+    Session = sessionmaker(bind=engine)
+    return Session()

pleasant_database-1.3.0/pleasant_database/database_file.py

@@ -0,0 +1,129 @@
+#!python3
+"""
+local_db.database_file.py
+
+this module creates, deletes, and archives database files within a python project
+
+required project structure:
+
+root\\
+|───data
+|   └──db_files
+|   └──log_dir 
+|───src
+└   └──package
+
+Class:
+    - DatabaseFile: a class which represents a db file object
+"""
+
+# Standard library imports
+import sqlite3
+
+# Third-party imports
+import os
+
+# local imports
+from . import DEFAULT_DB_DIRECTORY
+from .utils import LoggingExtras, check_db_exists, is_db_file
+
+# Initialize module logger
+import logging
+logger = logging.getLogger(__name__)
+
+
+
+class DatabaseFile():
+    """
+    Class which manages a single database file, name attribute must be valid .db filename
+
+    Functions:
+        - exxists: checks if the database file exists in the given directory
+        - create: creates a new database file in the given directory
+        - move: moves the database file to a new directory
+        - delete: deletes the database file from the filesystem
+    """
+    def __init__(self, name, directory=DEFAULT_DB_DIRECTORY):
+        """
+        initializes a DatabaseFile object with a name and directory
+
+        Args:
+            name (str): the name of the database file, must be a valid .db filename
+            directory (str): the relative directory where the database file is located, default is "os.curdir/data/db_files"
+        """
+        # Check if the name is a valid database filename
+        if is_db_file(name):
+            self.name = name
+        else:
+            logger.error(f"{name} is not a valid database filename.", extra={LoggingExtras.FILE: name})
+            raise ValueError(f"Database file {name} is not a valid database filename.")
+        
+        # Initialize the directory and path attributes
+        self.directory = directory
+        self.file_path = os.path.join(self.directory, self.name)
+        self.abspath = os.path.abspath(self.file_path)
+
+        # If the directory does not exist, create it
+        if not os.path.exists(self.directory):
+            logger.warning(f"Database directory {directory} does not exist. Creating directory...", extra={LoggingExtras.FILE: directory})
+            os.makedirs(directory)
+
+
+    def exists(self) -> bool:
+        """checks the if the database name exists in the given directiry""" 
+        return check_db_exists(self.name, self.directory)
+    
+
+    def create(self):
+        """creates a new database file in a given directory, default .\\data."""
+        logger.info(f"Creating database file {self.name}...")
+        if self.exists():
+            logger.info(f"Database file {self.name} already exists in {self.directory}", extra={LoggingExtras.FILE: os.path.join(self.directory, self.name)})
+        else:
+            sqlite3.connect(self.file_path).close()
+            logger.info(f"Database file {self.name} created.", extra={LoggingExtras.FILE: self.name})
+            logger.debug(f"New db file path: {self.file_path}", extra={LoggingExtras.FILE: self.file_path})
+
+
+    def move(self, target_directory: str) -> None:
+        """moves a DatabaseFile object to a new directory"""
+        logger.info(f"Moving {self.name} from {self.directory} to {target_directory}...", extra={
+                                                                                        LoggingExtras.FILE: self.name, 
+                                                                                        LoggingExtras.FILE: target_directory
+                                                                                        })
+
+        # Check if db with that filename already exists in target dir. return False, not moved
+        target_exists = check_db_exists(self.name, target_directory)
+        if target_exists:
+            # Does nothing if it already exists
+            logger.error(f"Database file {self.name} already exists in {target_directory}.", extra={
+                                                                                        LoggingExtras.FILE: self.name, 
+                                                                                        LoggingExtras.FILE: target_directory
+                                                                                        })
+        elif self.exists():
+            # Moves to new directory if it doesn"t exist and the current file exists
+            new_path = os.path.join(target_directory, self.name)
+            os.rename(self.file_path, new_path)
+            self.file_path = new_path
+            self.abspath = os.path.abspath(self.file_path)
+            self.directory = target_directory
+        else:
+            logger.error(f"Database file {self.name} cannot be moved because it doesn't exist in {self.directory}", extra={
+                                                                                        LoggingExtras.FILE: self.name, 
+                                                                                        LoggingExtras.FILE: self.directory
+                                                                                        })
+            
+
+    def delete(self):
+        """deletes the file managed by the DatabaseFile instance"""
+        if os.path.exists(self.abspath):
+            os.remove(self.abspath)
+            logger.info(f"Database file {self.name} deleted from {self.directory}...", extra={
+                                                                                        LoggingExtras.FILE: self.name, 
+                                                                                        LoggingExtras.FILE: self.directory
+                                                                                        })
+        else:
+            logger.error(f"DatabaseFile.delete() -> {self.name} does not exist in {self.directory}. Cannot delete.", extra={
+                                                                                                                    LoggingExtras.FILE: self.name, 
+                                                                                                                    LoggingExtras.FILE: self.directory
+                                                                                                                    })