SQLDbWrpr 5.0.1__tar.gz → 5.1.0__tar.gz

{sqldbwrpr-5.0.1 → sqldbwrpr-5.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SQLDbWrpr
-Version: 5.0.1
+Version: 5.1.0
 Summary: Wrapper for importing CSV and Text files into MySQL and Postgress
 License-Expression: MIT
 License-File: LICENSE.txt
@@ -8,23 +8,26 @@ Author: Hendrik du Toit
 Author-email: hendrik@brightedge.co.za
 Maintainer: Hendrik du Toit
 Maintainer-email: hendrikdt@citiqprepaid.co.za
-Requires-Python: >=3.10
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Intended Audience :: Information Technology
-Classifier: Topic :: Software Development
-Classifier: Topic :: Text Processing
-Classifier: Topic :: Utilities
+Requires-Python: >=3.10,<3.15
+Classifier: Development Status :: 6 - Mature
+Classifier: Framework :: Pydantic :: 2
+Classifier: Framework :: Pytest
 Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: iOS
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Dist: csvwrpr (>=1.16.1,<2.0.0)
 Requires-Dist: fixdate (>=2.1.0,<3.0.0)
 Requires-Dist: mysql-connector (>=2.2.9,<3.0.0)
+Requires-Dist: psycopg[binary] (>=3.2.0,<4.0.0)
 Requires-Dist: pydantic-settings (>=2.12.0,<3.0.0)
-Requires-Dist: pyodbc (>=5.3.0,<6.0.0)
+Requires-Dist: sqlalchemy (>=2.0.0,<3.0.0)
 Project-URL: Homepage, https://github.com/BrightEdgeeServices/SqlDbWrpr
 Project-URL: Issues, https://github.com/BrightEdgeeServices/SqlDbWrpr/issues
 Project-URL: Repository, https://github.com/BrightEdgeeServices/SqlDbWrpr.git
@@ -40,20 +43,39 @@ Description-Content-Type: text/markdown
 | PyPI         | [![][pypi_release_img]][pypi_release_lnk] [![][pypi_py_versions_img]][pypi_py_versions_lnk] [![][pypi_format_img]][pypi_format_lnk] [![][pypi_downloads_img]][pypi_downloads_lnk]             |
 | Github       | [![][gh_issues_img]][gh_issues_lnk] [![][gh_language_img]][gh_language_lnk] [![][gh_last_commit_img]][gh_last_commit_lnk] [![][gh_deployment_img]][gh_deployment_lnk]                         |
 
-## Overview
+## Short description
 
-SqlDbWrpr is a Python-based utility designed to simplify interactions with SQL databases, specifically MySQL and MSSQL. It provides a high-level abstraction for common database operations, making it easier to manage database schemas, import/export data, and handle user permissions.
+SqlDbWrpr is a Python wrapper that streamlines schema creation plus CSV import/export workflows for SQL backends.
+
+## Module Overview
+
+SqlDbWrpr is a Python utility for creating SQL database schemas and moving CSV data into and out of those schemas. It currently provides wrappers for MySQL and PostgreSQL.
+
+Schemas can be supplied in two ways:
+
+1. A legacy `db_structure` dictionary.
+2. SQLAlchemy metadata, either directly through `p_sqlalchemy_metadata` or through `p_sqlalchemy_base.metadata`.
+
+When both are supplied, `p_db_structure` takes precedence for backward compatibility. If no supported schema source is supplied, `SchemaSourceError` is raised.
 
 ### Key Features
 
-- **Schema Management**: Define your database structure (tables, fields, types, primary keys, foreign keys, and indexes) using a simple Python dictionary. SqlDbWrpr handles the creation of the database and tables based on this definition.
+- **Schema Management**: Create databases, tables, primary keys, foreign keys, and indexes from a legacy dictionary or SQLAlchemy metadata.
 - **Data Import/Export**:
-  - Effortlessly import data from CSV files into your SQL tables. It supports both single and multi-volume CSV files and handles data type conversions and date formatting.
-  - Export table data or custom SQL query results back to CSV files, with options for multi-volume exports if the data size is large.
-- **User and Permission Management**: Create and delete database users and grant them specific rights across the database.
-- **SSL Support**: Secure your database connections with built-in support for SSL CA, key, and certificate files.
-- **Batch Processing**: Optimize performance during data imports with configurable batch sizes.
-- **Multi-Database Support**: Includes dedicated classes for MySQL and MSSQL, ensuring compatibility across different SQL environments.
+  - Import CSV data from files or in-memory rows, including single-volume and numbered multi-volume files.
+  - Export full tables or custom SQL query results to CSV, including optional multi-volume exports.
+- **Database Support**: Includes MySQL and PostgreSQL wrappers with dialect-specific SQL rendering.
+- **User and Permission Management**: Create MySQL users and grant database rights.
+- **Batch Processing**: Configure import batch sizes for larger CSV loads.
+
+### Project Structure
+
+- `src/sqldbwrpr/`: Core library implementation, including MySQL and PostgreSQL wrappers.
+- `tests/`: Unit and integration-oriented test coverage for wrapper behaviour.
+- `scripts/`: SQL setup/bootstrap assets used for database initialization.
+- Root automation scripts (`*.ps1`) and CI configuration under `.github/workflows/` support setup and delivery.
+
+## Getting Started
 
 ### Installation
 
@@ -61,24 +83,46 @@ SqlDbWrpr is a Python-based utility designed to simplify interactions with SQL d
 pip install SqlDbWrpr
 ```
 
-### Quick Start
+### Quick Start With A Legacy Structure
 
 ```python
 from sqldbwrpr.sqldbwrpr import MySQL
 
-# Define your database structure
+field_defaults = {
+    "PrimaryKey": ["", ""],
+    "FKey": [],
+    "Index": [],
+    "NN": "",
+    "B": "",
+    "UN": "",
+    "ZF": "",
+    "AI": "",
+    "G": "",
+    "DEF": "",
+}
+
 db_structure = {
     "Users": {
         "ID": {
             "Type": ["int"],
-            "Params": {"PrimaryKey": ["Y", "A"], "NN": "Y", "AI": "Y"},
+            "Params": {
+                **field_defaults,
+                "PrimaryKey": ["Y", "A"],
+                "NN": "Y",
+                "AI": "Y",
+            },
+            "Possible Values": "",
+            "Comment": "",
+        },
+        "Username": {
+            "Type": ["varchar", 50],
+            "Params": {**field_defaults, "NN": "Y"},
+            "Possible Values": "",
+            "Comment": "",
         },
-        "Username": {"Type": ["varchar", 50], "Params": {"NN": "Y"}},
-        "Email": {"Type": ["varchar", 100], "Params": {"NN": "Y"}},
     }
 }
 
-# Initialize the wrapper
 db = MySQL(
     p_host_name="localhost",
     p_user_name="root",
@@ -88,13 +132,82 @@ db = MySQL(
     p_recreate_db=True,
 )
 
-# Import data from CSV
-db.import_csv("Users", "users_data.csv")
-
-# Export data to CSV
+db.import_csv("Users", p_csv_db=[("Username",), ("alice",)], p_vol_type="Single")
 db.export_to_csv("exported_users.csv", "Users")
 ```
 
+### Quick Start With SQLAlchemy Metadata
+
+```python
+from sqlalchemy import Column
+from sqlalchemy import Integer
+from sqlalchemy import MetaData
+from sqlalchemy import String
+from sqlalchemy import Table
+
+from sqldbwrpr.sqldbwrpr import PostgreSQL
+
+metadata = MetaData()
+Table(
+    "Users",
+    metadata,
+    Column("ID", Integer, primary_key=True, autoincrement=True),
+    Column("Username", String(50), nullable=False),
+)
+
+db = PostgreSQL(
+    p_host_name="localhost",
+    p_user_name="postgres",
+    p_password="yourpassword",
+    p_db_name="my_database",
+    p_sqlalchemy_metadata=metadata,
+    p_recreate_db=True,
+)
+
+db.import_csv("Users", p_csv_db=[("Username",), ("alice",)], p_vol_type="Single")
+```
+
+______________________________________________________________________
+
+## Updating ReleaseNotes Instructions
+
+1. Run the `pushpy.ps1` script or manually commit the current changes.
+2. Generate the release notes
+3. Use one of the following AI propmpts in Notion to generate the release notes.
+
+- [Release - Update - General](https://www.notion.so/Release-Update-General-2c0bc8e6c6f38076b4cee82e3cf243fa?v=2c0bc8e6c6f3806e85db000c395f94ce&source=copy_link)
+- [Release - Update - VenvIt](https://www.notion.so/Release-Update-VenvIt-2c0bc8e6c6f380de84a0f3fbb8b5dda5?v=2c0bc8e6c6f3806e85db000c395f94ce&source=copy_link)
+
+or
+
+1. Use the following template and manually update the ReleaseNotes.md file.
+
+   ```
+    # Release ?.?.?
+    ## Summary of Changes
+    - bla, bla, bla
+    ## Next Heading
+    - bla, bla, bla
+    ---
+   ```
+
+2. You can repeat step 1 multiple times.
+
+3. You can repeat step 2 multiple times but update the ReleaseNotes that has not been published.
+
+4. Run the `pushpr.ps1` script once you are ready to create the PR to publish the release. TOy can also manually create
+   the tag, touch a file, commit and push the changes.
+
+5. Merge the PR in GitHub.
+
+6. Confirm the following:
+
+7. The release update reflects in GitHub
+
+8. The release update notification was sent
+
+______________________________________________________________________
+
 [cicd_codestyle_img]: https://img.shields.io/badge/code%20style-black-000000.svg "Black"
 [cicd_codestyle_lnk]: https://github.com/psf/black "Black"
 [cicd_pre_commit_img]: https://img.shields.io/github/actions/workflow/status/BrightEdgeeServices/SqlDbWrpr/pre-commit.yml?label=pre-commit "Pre-Commit"

{sqldbwrpr-5.0.1 → sqldbwrpr-5.1.0}/README.md

@@ -7,20 +7,39 @@
 | PyPI         | [![][pypi_release_img]][pypi_release_lnk] [![][pypi_py_versions_img]][pypi_py_versions_lnk] [![][pypi_format_img]][pypi_format_lnk] [![][pypi_downloads_img]][pypi_downloads_lnk]             |
 | Github       | [![][gh_issues_img]][gh_issues_lnk] [![][gh_language_img]][gh_language_lnk] [![][gh_last_commit_img]][gh_last_commit_lnk] [![][gh_deployment_img]][gh_deployment_lnk]                         |
 
-## Overview
+## Short description
 
-SqlDbWrpr is a Python-based utility designed to simplify interactions with SQL databases, specifically MySQL and MSSQL. It provides a high-level abstraction for common database operations, making it easier to manage database schemas, import/export data, and handle user permissions.
+SqlDbWrpr is a Python wrapper that streamlines schema creation plus CSV import/export workflows for SQL backends.
+
+## Module Overview
+
+SqlDbWrpr is a Python utility for creating SQL database schemas and moving CSV data into and out of those schemas. It currently provides wrappers for MySQL and PostgreSQL.
+
+Schemas can be supplied in two ways:
+
+1. A legacy `db_structure` dictionary.
+2. SQLAlchemy metadata, either directly through `p_sqlalchemy_metadata` or through `p_sqlalchemy_base.metadata`.
+
+When both are supplied, `p_db_structure` takes precedence for backward compatibility. If no supported schema source is supplied, `SchemaSourceError` is raised.
 
 ### Key Features
 
-- **Schema Management**: Define your database structure (tables, fields, types, primary keys, foreign keys, and indexes) using a simple Python dictionary. SqlDbWrpr handles the creation of the database and tables based on this definition.
+- **Schema Management**: Create databases, tables, primary keys, foreign keys, and indexes from a legacy dictionary or SQLAlchemy metadata.
 - **Data Import/Export**:
-  - Effortlessly import data from CSV files into your SQL tables. It supports both single and multi-volume CSV files and handles data type conversions and date formatting.
-  - Export table data or custom SQL query results back to CSV files, with options for multi-volume exports if the data size is large.
-- **User and Permission Management**: Create and delete database users and grant them specific rights across the database.
-- **SSL Support**: Secure your database connections with built-in support for SSL CA, key, and certificate files.
-- **Batch Processing**: Optimize performance during data imports with configurable batch sizes.
-- **Multi-Database Support**: Includes dedicated classes for MySQL and MSSQL, ensuring compatibility across different SQL environments.
+  - Import CSV data from files or in-memory rows, including single-volume and numbered multi-volume files.
+  - Export full tables or custom SQL query results to CSV, including optional multi-volume exports.
+- **Database Support**: Includes MySQL and PostgreSQL wrappers with dialect-specific SQL rendering.
+- **User and Permission Management**: Create MySQL users and grant database rights.
+- **Batch Processing**: Configure import batch sizes for larger CSV loads.
+
+### Project Structure
+
+- `src/sqldbwrpr/`: Core library implementation, including MySQL and PostgreSQL wrappers.
+- `tests/`: Unit and integration-oriented test coverage for wrapper behaviour.
+- `scripts/`: SQL setup/bootstrap assets used for database initialization.
+- Root automation scripts (`*.ps1`) and CI configuration under `.github/workflows/` support setup and delivery.
+
+## Getting Started
 
 ### Installation
 
@@ -28,24 +47,46 @@ SqlDbWrpr is a Python-based utility designed to simplify interactions with SQL d
 pip install SqlDbWrpr
 ```
 
-### Quick Start
+### Quick Start With A Legacy Structure
 
 ```python
 from sqldbwrpr.sqldbwrpr import MySQL
 
-# Define your database structure
+field_defaults = {
+    "PrimaryKey": ["", ""],
+    "FKey": [],
+    "Index": [],
+    "NN": "",
+    "B": "",
+    "UN": "",
+    "ZF": "",
+    "AI": "",
+    "G": "",
+    "DEF": "",
+}
+
 db_structure = {
     "Users": {
         "ID": {
             "Type": ["int"],
-            "Params": {"PrimaryKey": ["Y", "A"], "NN": "Y", "AI": "Y"},
+            "Params": {
+                **field_defaults,
+                "PrimaryKey": ["Y", "A"],
+                "NN": "Y",
+                "AI": "Y",
+            },
+            "Possible Values": "",
+            "Comment": "",
+        },
+        "Username": {
+            "Type": ["varchar", 50],
+            "Params": {**field_defaults, "NN": "Y"},
+            "Possible Values": "",
+            "Comment": "",
         },
-        "Username": {"Type": ["varchar", 50], "Params": {"NN": "Y"}},
-        "Email": {"Type": ["varchar", 100], "Params": {"NN": "Y"}},
     }
 }
 
-# Initialize the wrapper
 db = MySQL(
     p_host_name="localhost",
     p_user_name="root",
@@ -55,13 +96,82 @@ db = MySQL(
     p_recreate_db=True,
 )
 
-# Import data from CSV
-db.import_csv("Users", "users_data.csv")
-
-# Export data to CSV
+db.import_csv("Users", p_csv_db=[("Username",), ("alice",)], p_vol_type="Single")
 db.export_to_csv("exported_users.csv", "Users")
 ```
 
+### Quick Start With SQLAlchemy Metadata
+
+```python
+from sqlalchemy import Column
+from sqlalchemy import Integer
+from sqlalchemy import MetaData
+from sqlalchemy import String
+from sqlalchemy import Table
+
+from sqldbwrpr.sqldbwrpr import PostgreSQL
+
+metadata = MetaData()
+Table(
+    "Users",
+    metadata,
+    Column("ID", Integer, primary_key=True, autoincrement=True),
+    Column("Username", String(50), nullable=False),
+)
+
+db = PostgreSQL(
+    p_host_name="localhost",
+    p_user_name="postgres",
+    p_password="yourpassword",
+    p_db_name="my_database",
+    p_sqlalchemy_metadata=metadata,
+    p_recreate_db=True,
+)
+
+db.import_csv("Users", p_csv_db=[("Username",), ("alice",)], p_vol_type="Single")
+```
+
+______________________________________________________________________
+
+## Updating ReleaseNotes Instructions
+
+1. Run the `pushpy.ps1` script or manually commit the current changes.
+2. Generate the release notes
+3. Use one of the following AI propmpts in Notion to generate the release notes.
+
+- [Release - Update - General](https://www.notion.so/Release-Update-General-2c0bc8e6c6f38076b4cee82e3cf243fa?v=2c0bc8e6c6f3806e85db000c395f94ce&source=copy_link)
+- [Release - Update - VenvIt](https://www.notion.so/Release-Update-VenvIt-2c0bc8e6c6f380de84a0f3fbb8b5dda5?v=2c0bc8e6c6f3806e85db000c395f94ce&source=copy_link)
+
+or
+
+1. Use the following template and manually update the ReleaseNotes.md file.
+
+   ```
+    # Release ?.?.?
+    ## Summary of Changes
+    - bla, bla, bla
+    ## Next Heading
+    - bla, bla, bla
+    ---
+   ```
+
+2. You can repeat step 1 multiple times.
+
+3. You can repeat step 2 multiple times but update the ReleaseNotes that has not been published.
+
+4. Run the `pushpr.ps1` script once you are ready to create the PR to publish the release. TOy can also manually create
+   the tag, touch a file, commit and push the changes.
+
+5. Merge the PR in GitHub.
+
+6. Confirm the following:
+
+7. The release update reflects in GitHub
+
+8. The release update notification was sent
+
+______________________________________________________________________
+
 [cicd_codestyle_img]: https://img.shields.io/badge/code%20style-black-000000.svg "Black"
 [cicd_codestyle_lnk]: https://github.com/psf/black "Black"
 [cicd_pre_commit_img]: https://img.shields.io/github/actions/workflow/status/BrightEdgeeServices/SqlDbWrpr/pre-commit.yml?label=pre-commit "Pre-Commit"

sqldbwrpr-5.1.0/pyproject.toml

@@ -0,0 +1,135 @@
+[build-system]
+    requires = [
+        "poetry-core>=2.0.0,<3.0.0",
+    ]
+    build-backend = "poetry.core.masonry.api"
+
+[project]
+    name = 'SQLDbWrpr'
+    version = '5.1.0'
+    description = 'Wrapper for importing CSV and Text files into MySQL and Postgress'
+    authors = [
+        { name = "Hendrik du Toit", email = "hendrik@brightedge.co.za" }
+    ]
+    classifiers = [
+        "Development Status :: 6 - Mature",
+        "Framework :: Pydantic :: 2",
+        "Framework :: Pytest",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: Microsoft :: Windows",
+        "Operating System :: POSIX :: Linux",
+        "Operating System :: iOS",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
+        "Programming Language :: Python :: 3.14",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+    ]
+    dependencies = [
+    "pydantic-settings (>=2.12.0,<3.0.0)",
+    "csvwrpr (>=1.16.1,<2.0.0)",
+    "fixdate (>=2.1.0,<3.0.0)",
+    "mysql-connector (>=2.2.9,<3.0.0)",
+    "sqlalchemy (>=2.0.0,<3.0.0)",
+    "psycopg[binary] (>=3.2.0,<4.0.0)",
+    ]
+    license = "MIT"
+#license = "Proprietary"
+    license-files = ["LICENSE.txt"]
+    maintainers = [
+        { name = "Hendrik du Toit", email = "hendrikdt@citiqprepaid.co.za" },
+        { name = "Henru du Toit", email = "henru@brightedge.co.za" },
+        { name = "Dirk du Toit", email = "dirk@brightedge.co.za" },
+    ]
+    readme = { file = "README.md", content-type = "text/markdown" }
+    requires-python = ">=3.10,<3.15"
+
+[project.urls]
+    # documentation = "https://readthedocs.org"
+    Issues = "https://github.com/BrightEdgeeServices/SqlDbWrpr/issues"
+    changelog = "https://github.com/BrightEdgeeServices/SqlDbWrpr/releases"
+    Homepage = "https://github.com/BrightEdgeeServices/SqlDbWrpr"
+    Repository = "https://github.com/BrightEdgeeServices/SqlDbWrpr.git"
+
+[tool.black]
+    line-length = 120
+    target-version = [
+        "py310",
+        "py311",
+        "py312",
+        "py313",
+        "py314",
+    ]
+    extend-exclude = """
+    (
+        ^tests/testdata.py
+    )
+    """
+
+[tool.codespell]
+    count = ""
+    quiet-level = 2
+    skip = "working/*,legacy/*,poetry.lock,tests/test_data/*"
+    ignore-words-list = "space-holder"
+    write-changes = ""
+
+[tool.coverage.run]
+    source = [
+        "src",
+        "tests"
+    ]
+    omit = [
+        "./legacy/*",
+        "tests/fixtures.py",
+    ]
+
+[tool.isort]
+    profile = "black"
+    src_paths = ["src", "tests"]
+
+[tool.poetry.group.dev]
+    optional = true
+
+[tool.poetry.group.dev.dependencies]
+    black = ">=25.1.0"
+    codecov = ">=2.1.13"
+    flake8 = ">=7.1.1"
+    isort = "^5.13.2"
+    mdformat-gfm = ">=0.4.1"
+    mdformat-frontmatter = ">=2.0.8"
+    mdformat-footnote = ">=0.1.1"
+    pluggy = ">=1.6.0,<2.0.0"
+    pre-commit = ">=4.0.1"
+    pygments = "^2.19.1"
+    pytest = ">=9.0.2"
+    pytest-cov = ">=6.0.0"
+    docker = ">=7.1.0"
+    twine = ">=6.1.0"
+
+[[tool.poetry.source]]
+name = "RTE"
+url = "https://github.com/BrightEdgeeServices/PoetryPrivate.git"
+priority = "explicit"
+
+[tool.poetry.dependencies]
+
+[tool.pytest.ini_options]
+    norecursedirs = ["tests/legacy"]
+    addopts = [
+        "-vv",
+        "--ignore-glob=*/Archive",
+        "--ignore=/legacy",
+        "--ignore=tests/legacy",
+    ]
+    filterwarnings = [
+        #    "ignore::DeprecationWarning",
+    ]
+    pythonpath = [
+        "src",
+        "tests",
+    ]
+    testpaths = "tests"
+    markers = [
+        "select: Run a selection of tests",
+    ]