dbmasta 0.1.0__tar.gz

dbmasta-0.1.0/LICENSE

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

dbmasta-0.1.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.1
+Name: dbmasta
+Version: 0.1.0
+Summary: A simple MariaDB client based on SQLAlchemy core
+Home-page: https://github.com/mastamatto/dbConnect
+Author: Matt Owen
+Author-email: matt@ca-automation.app
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sqlalchemy>=2.0.27
+Requires-Dist: asyncmy
+Requires-Dist: pymysql
+
+# dbConnect (simple mariadb interface)
+
+## Overview
+
+This Python package provides a simple interface for interacting with MariaDB databases using SQLAlchemy Core. It abstracts some common database operations into more manageable Python methods, allowing for easy database queries, inserts, updates, and deletes.
+
+## Installation
+
+To install this package, run the following pip command. **Note: this requires SQLAlchemy 2.0.27 or greater**
+
+```bash
+pip install dbConnect
+```
+
+Replace `yourusername/yourrepository` with the actual path to your repository.
+
+## Basic Usage
+
+### Configuration
+
+First, configure the database client with the necessary credentials:
+
+```python
+from dbConnect import DataBase, AsyncDataBase
+
+# Initialize the database client
+db = DataBase(
+    dict(
+        username='username', 
+        password='password', 
+        host='host', 
+        port=3306, 
+        database_name='database_name'
+        )
+    )
+# Async Version
+db = AsyncDataBase(
+    dict(
+        username='username', 
+        password='password', 
+        host='host', 
+        port=3306, 
+        database_name='database_name'
+        )
+    )
+
+
+# Initiliaze using environment variables
+db = DataBase.env()
+# Async Version
+db = AsyncDataBase.env()
+```
+
+### Executing Queries
+
+You can execute a simple SELECT query to fetch data:
+
+```python
+import datetime as dt
+
+# Create parameters
+params = {
+    "date": db.before(dt.date(2024,1,1), inclusive=True)
+}
+
+# Execute the query
+dbr = db.select("database", "table", params)
+
+# Examine the results
+if dbr.successful:
+    print(dbr.records)
+else:
+    print(dbr.error_info)
+```
+
+### Complex Queries
+
+The following query would generate this text:
+
+```python
+import datetime as dt
+
+# Create parameters
+params = {
+    "_OR_": db.or_(
+        [
+            {"date": db.after(dt.date(2020,1,1)), "category": "sales"},
+            {"date": db.before(dt.date(2020,1,1)), "category": db.not_(db.in_, ["purchases","adjustments","sales"])},
+        ]
+    ),
+    "_AND_": db.and_(
+        [
+            {"keyfield": db.starts_with("SJ")},
+            {"keyfield": db.not_(db.ends_with("2E"))}
+        ]
+    )
+    "status": "under_review"
+}
+
+# Execute the query
+dbr = db.select("database", "table", params)
+
+# Examine the results
+if dbr.successful:
+    print(dbr.records)
+else:
+    print(dbr.error_info)
+```
+
+The raw text of the query can be retrieved from the attribute `dbr.raw_query` from the DataBaseResponse object,
+which the DataBase.select method returns. The text in the above example would be as follows:
+
+```sql
+SELECT * FROM `database`.`table`
+WHERE ((`date` > '2020-01-01' and `category`='sales') or 
+(`date` < '2020-01-01' and `category` not in ('sales')))
+AND `keyfield` LIKE 'SJ%' AND `keyfield` NOT LIKE '%2E'
+AND `status`='under_review';
+```
+
+Or in simple terms...
+Get all records `under_review` where the keyfield starts with `SJ`, but doesn't end with `2E`. Pull these if either:
+
+- dated after `2020-01-01` and categorized as a `sale`
+- dated before `2020-01-01` and not categorized as `sale`,`purchase` or `adjustment`.
+
+
+### Result Modification from `DataBase.select`
+
+In addition to complex conditions for filtering records, you can:
+
+- sort records
+
+    ```pythoN
+    db.select(..., order_by="column_name", reverse=True)
+    ```
+
+- limit and offset results
+
+    ```python
+    # for offset pagination
+    db.select(..., limit=100, offset=0)
+    ```
+
+- filter columns
+
+    ```python
+    # only receive the data for the fields you provide
+    db.select(..., columns=["keyfield", "name", "date"])
+    ```
+
+- get textual output (without executing)
+
+    ```python
+    # this will not execute the query, but will return the raw query needed to execute
+    raw_textual_query = db.select(..., textual=True)
+    print(raw_textual_query)
+    new_query = f"INSERT INTO `filteredtable` ({raw_textual_query[:-1]});
+    dbr = db.run(new_query)
+    ```
+
+- get model output by providing a model factory
+
+    ```python
+    from pydantic import BaseModel
+    import datetime as dt
+
+    class Record(BaseModel):
+        keyfield: str
+        date: dt.date
+        status: str
+
+    model_factory = lambda row: Record(**row)
+
+    # only receive the data for the fields you provide
+    dbr = db.select(..., response_model=model_factory)
+    # each record will be an instance of Record
+    ```

dbmasta-0.1.0/README.md

@@ -0,0 +1,178 @@
+# dbConnect (simple mariadb interface)
+
+## Overview
+
+This Python package provides a simple interface for interacting with MariaDB databases using SQLAlchemy Core. It abstracts some common database operations into more manageable Python methods, allowing for easy database queries, inserts, updates, and deletes.
+
+## Installation
+
+To install this package, run the following pip command. **Note: this requires SQLAlchemy 2.0.27 or greater**
+
+```bash
+pip install dbConnect
+```
+
+Replace `yourusername/yourrepository` with the actual path to your repository.
+
+## Basic Usage
+
+### Configuration
+
+First, configure the database client with the necessary credentials:
+
+```python
+from dbConnect import DataBase, AsyncDataBase
+
+# Initialize the database client
+db = DataBase(
+    dict(
+        username='username', 
+        password='password', 
+        host='host', 
+        port=3306, 
+        database_name='database_name'
+        )
+    )
+# Async Version
+db = AsyncDataBase(
+    dict(
+        username='username', 
+        password='password', 
+        host='host', 
+        port=3306, 
+        database_name='database_name'
+        )
+    )
+
+
+# Initiliaze using environment variables
+db = DataBase.env()
+# Async Version
+db = AsyncDataBase.env()
+```
+
+### Executing Queries
+
+You can execute a simple SELECT query to fetch data:
+
+```python
+import datetime as dt
+
+# Create parameters
+params = {
+    "date": db.before(dt.date(2024,1,1), inclusive=True)
+}
+
+# Execute the query
+dbr = db.select("database", "table", params)
+
+# Examine the results
+if dbr.successful:
+    print(dbr.records)
+else:
+    print(dbr.error_info)
+```
+
+### Complex Queries
+
+The following query would generate this text:
+
+```python
+import datetime as dt
+
+# Create parameters
+params = {
+    "_OR_": db.or_(
+        [
+            {"date": db.after(dt.date(2020,1,1)), "category": "sales"},
+            {"date": db.before(dt.date(2020,1,1)), "category": db.not_(db.in_, ["purchases","adjustments","sales"])},
+        ]
+    ),
+    "_AND_": db.and_(
+        [
+            {"keyfield": db.starts_with("SJ")},
+            {"keyfield": db.not_(db.ends_with("2E"))}
+        ]
+    )
+    "status": "under_review"
+}
+
+# Execute the query
+dbr = db.select("database", "table", params)
+
+# Examine the results
+if dbr.successful:
+    print(dbr.records)
+else:
+    print(dbr.error_info)
+```
+
+The raw text of the query can be retrieved from the attribute `dbr.raw_query` from the DataBaseResponse object,
+which the DataBase.select method returns. The text in the above example would be as follows:
+
+```sql
+SELECT * FROM `database`.`table`
+WHERE ((`date` > '2020-01-01' and `category`='sales') or 
+(`date` < '2020-01-01' and `category` not in ('sales')))
+AND `keyfield` LIKE 'SJ%' AND `keyfield` NOT LIKE '%2E'
+AND `status`='under_review';
+```
+
+Or in simple terms...
+Get all records `under_review` where the keyfield starts with `SJ`, but doesn't end with `2E`. Pull these if either:
+
+- dated after `2020-01-01` and categorized as a `sale`
+- dated before `2020-01-01` and not categorized as `sale`,`purchase` or `adjustment`.
+
+
+### Result Modification from `DataBase.select`
+
+In addition to complex conditions for filtering records, you can:
+
+- sort records
+
+    ```pythoN
+    db.select(..., order_by="column_name", reverse=True)
+    ```
+
+- limit and offset results
+
+    ```python
+    # for offset pagination
+    db.select(..., limit=100, offset=0)
+    ```
+
+- filter columns
+
+    ```python
+    # only receive the data for the fields you provide
+    db.select(..., columns=["keyfield", "name", "date"])
+    ```
+
+- get textual output (without executing)
+
+    ```python
+    # this will not execute the query, but will return the raw query needed to execute
+    raw_textual_query = db.select(..., textual=True)
+    print(raw_textual_query)
+    new_query = f"INSERT INTO `filteredtable` ({raw_textual_query[:-1]});
+    dbr = db.run(new_query)
+    ```
+
+- get model output by providing a model factory
+
+    ```python
+    from pydantic import BaseModel
+    import datetime as dt
+
+    class Record(BaseModel):
+        keyfield: str
+        date: dt.date
+        status: str
+
+    model_factory = lambda row: Record(**row)
+
+    # only receive the data for the fields you provide
+    dbr = db.select(..., response_model=model_factory)
+    # each record will be an instance of Record
+    ```

dbmasta-0.1.0/dbmasta/__init__.py

@@ -0,0 +1,3 @@
+# -*- coding: utf-8 -*-
+from .async_db_client import AsyncDataBase
+from .db_client import DataBase

dbmasta-0.1.0/dbmasta/async_db_client/__init__.py

@@ -0,0 +1 @@
+from .base import AsyncDataBase