pymnemon 0.1.1__py3-none-any.whl

mnemon/utils/error_handling.py

@@ -0,0 +1,180 @@
+"""
+Connection error normalization for user-friendly feedback.
+Maps database-specific errors to actionable messages.
+"""
+
+from enum import Enum
+from typing import Optional
+from dataclasses import dataclass
+import re
+
+
+class ErrorCategory(Enum):
+    AUTH_FAILED = "auth_failed"
+    NETWORK_UNREACHABLE = "network_unreachable"
+    DATABASE_NOT_FOUND = "database_not_found"
+    SCHEMA_NOT_FOUND = "schema_not_found"
+    TABLE_NOT_FOUND = "table_not_found"
+    PERMISSION_DENIED = "permission_denied"
+    SSL_ERROR = "ssl_error"
+    TIMEOUT = "timeout"
+    INVALID_CONFIG = "invalid_config"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class NormalizedError:
+    category: ErrorCategory
+    message: str
+    next_steps: list[str]
+    original_error: str
+    field_hint: Optional[str] = None  # Which form field is likely wrong
+
+
+# Error patterns per database
+ERROR_PATTERNS = {
+    "postgresql": [
+        (r"password authentication failed", ErrorCategory.AUTH_FAILED, ["Verify username and password", "Ensure user exists in PostgreSQL"]),
+        (r"could not connect to server.*Connection refused", ErrorCategory.NETWORK_UNREACHABLE, ["Verify host and port", "Check if PostgreSQL is running", "Check firewall rules"]),
+        (r"database .* does not exist", ErrorCategory.DATABASE_NOT_FOUND, ["Verify database name", "Check spelling"]),
+        (r"SSL.*certificate", ErrorCategory.SSL_ERROR, ["Verify SSL certificate paths", "Check certificate validity"]),
+        (r"permission denied", ErrorCategory.PERMISSION_DENIED, ["Check user privileges", "Contact database administrator"]),
+        (r"timeout", ErrorCategory.TIMEOUT, ["Check network connectivity", "Increase timeout settings"]),
+    ],
+
+    "snowflake": [
+        (r"Incorrect username or password", ErrorCategory.AUTH_FAILED, ["Verify username and password", "Check account identifier format"]),
+        (r"JWT token is invalid", ErrorCategory.AUTH_FAILED, ["Verify private key matches public key in Snowflake", "Check key pair configuration"]),
+        (r"account .* does not exist", ErrorCategory.INVALID_CONFIG, ["Verify account identifier", "Include region if required (e.g., xy12345.us-east-1)"]),
+        (r"Warehouse .* does not exist", ErrorCategory.INVALID_CONFIG, ["Verify warehouse name", "Check warehouse is created and accessible"]),
+        (r"Database .* does not exist", ErrorCategory.DATABASE_NOT_FOUND, ["Verify database name", "Check user has access to database"]),
+        (r"IP .* is not allowed", ErrorCategory.NETWORK_UNREACHABLE, ["Add your IP to Snowflake network policy", "Contact Snowflake administrator"]),
+    ],
+
+    "bigquery": [
+        (r"Could not deserialize key data", ErrorCategory.AUTH_FAILED, ["Verify service account JSON is valid", "Re-download credentials from GCP Console"]),
+        (r"403.*Access Denied", ErrorCategory.PERMISSION_DENIED, ["Verify service account has BigQuery permissions", "Check IAM roles in GCP Console"]),
+        (r"404.*Not found: Project", ErrorCategory.INVALID_CONFIG, ["Verify project ID", "Check project exists and is accessible"]),
+        (r"404.*Not found: Dataset", ErrorCategory.SCHEMA_NOT_FOUND, ["Verify dataset name", "Check dataset exists in project"]),
+    ],
+
+    "redshift": [
+        (r"password authentication failed", ErrorCategory.AUTH_FAILED, ["Verify username and password", "Ensure user exists in Redshift"]),
+        (r"could not connect to server", ErrorCategory.NETWORK_UNREACHABLE, ["Verify cluster endpoint", "Check VPC security groups", "Ensure cluster is publicly accessible or VPN is connected"]),
+        (r"database .* does not exist", ErrorCategory.DATABASE_NOT_FOUND, ["Verify database name"]),
+    ],
+
+    "mysql": [
+        (r"Access denied for user", ErrorCategory.AUTH_FAILED, ["Verify username and password", "Check user host permissions"]),
+        (r"Can't connect to MySQL server", ErrorCategory.NETWORK_UNREACHABLE, ["Verify host and port", "Check if MySQL is running"]),
+        (r"Unknown database", ErrorCategory.DATABASE_NOT_FOUND, ["Verify database name"]),
+        (r"SSL connection error", ErrorCategory.SSL_ERROR, ["Verify SSL certificate paths", "Check certificate validity"]),
+    ],
+
+    "clickhouse": [
+        (r"Authentication failed", ErrorCategory.AUTH_FAILED, ["Verify username and password"]),
+        (r"Connection refused", ErrorCategory.NETWORK_UNREACHABLE, ["Verify host and port", "Check if ClickHouse is running"]),
+        (r"Database .* doesn't exist", ErrorCategory.DATABASE_NOT_FOUND, ["Verify database name"]),
+    ],
+
+    "databricks": [
+        (r"Invalid access token", ErrorCategory.AUTH_FAILED, ["Generate new Personal Access Token in Databricks", "Verify token has not expired"]),
+        (r"Could not resolve host", ErrorCategory.NETWORK_UNREACHABLE, ["Verify workspace URL", "Check network connectivity"]),
+        (r"HTTP 404", ErrorCategory.INVALID_CONFIG, ["Verify HTTP path for SQL warehouse", "Check warehouse exists"]),
+    ],
+
+    "athena": [
+        (r"InvalidAccessKeyId", ErrorCategory.AUTH_FAILED, ["Verify AWS access key ID"]),
+        (r"SignatureDoesNotMatch", ErrorCategory.AUTH_FAILED, ["Verify AWS secret access key"]),
+        (r"Access Denied", ErrorCategory.PERMISSION_DENIED, ["Check IAM permissions for Athena and S3", "Verify S3 staging directory access"]),
+        (r"Database .* not found", ErrorCategory.DATABASE_NOT_FOUND, ["Verify schema/database name in Glue catalog"]),
+    ],
+
+    # Default patterns for databases without specific patterns
+    "_default": [
+        (r"authentication|password|credential|login failed", ErrorCategory.AUTH_FAILED, ["Verify username and password"]),
+        (r"connection refused|could not connect|unreachable|host", ErrorCategory.NETWORK_UNREACHABLE, ["Verify host and port", "Check network connectivity"]),
+        (r"database.*not exist|unknown database", ErrorCategory.DATABASE_NOT_FOUND, ["Verify database name"]),
+        (r"permission denied|access denied|not authorized", ErrorCategory.PERMISSION_DENIED, ["Check user permissions"]),
+        (r"ssl|certificate|tls", ErrorCategory.SSL_ERROR, ["Check SSL configuration"]),
+        (r"timeout|timed out", ErrorCategory.TIMEOUT, ["Check network connectivity", "Increase timeout"]),
+    ],
+}
+
+# Field hints for common error categories
+FIELD_HINTS = {
+    ErrorCategory.AUTH_FAILED: "user or password",
+    ErrorCategory.NETWORK_UNREACHABLE: "host or port",
+    ErrorCategory.DATABASE_NOT_FOUND: "database",
+    ErrorCategory.SCHEMA_NOT_FOUND: "schema",
+    ErrorCategory.SSL_ERROR: "SSL certificate fields",
+    ErrorCategory.INVALID_CONFIG: "account or connection details",
+}
+
+
+def normalize_error(database_type: str, error: Exception) -> NormalizedError:
+    """
+    Convert database-specific error to normalized, user-friendly format.
+    
+    Args:
+        database_type: The database type (e.g., 'postgresql', 'snowflake')
+        error: The original exception
+    
+    Returns:
+        NormalizedError with category, message, and actionable next steps
+    """
+    error_str = str(error).lower()
+    original_error = str(error)
+
+    # Get patterns for this database type, fallback to default
+    patterns = ERROR_PATTERNS.get(database_type, []) + ERROR_PATTERNS["_default"]
+
+    for pattern, category, next_steps in patterns:
+        if re.search(pattern, error_str, re.IGNORECASE):
+            return NormalizedError(
+                category=category,
+                message=_get_user_message(category),
+                next_steps=next_steps,
+                original_error=original_error,
+                field_hint=FIELD_HINTS.get(category),
+            )
+
+    # Unknown error
+    return NormalizedError(
+        category=ErrorCategory.UNKNOWN,
+        message="An unexpected error occurred while connecting to the database.",
+        next_steps=["Check connection details", "Review error message below", "Contact support if issue persists"],
+        original_error=original_error,
+        field_hint=None,
+    )
+
+
+def _get_user_message(category: ErrorCategory) -> str:
+    """Get user-friendly message for error category."""
+    messages = {
+        ErrorCategory.AUTH_FAILED: "Authentication failed. Please check your credentials.",
+        ErrorCategory.NETWORK_UNREACHABLE: "Unable to reach the database server.",
+        ErrorCategory.DATABASE_NOT_FOUND: "The specified database was not found.",
+        ErrorCategory.SCHEMA_NOT_FOUND: "The specified schema was not found.",
+        ErrorCategory.TABLE_NOT_FOUND: "The specified table was not found.",
+        ErrorCategory.PERMISSION_DENIED: "You don't have permission to perform this action.",
+        ErrorCategory.SSL_ERROR: "SSL/TLS connection error. Check certificate configuration.",
+        ErrorCategory.TIMEOUT: "Connection timed out.",
+        ErrorCategory.INVALID_CONFIG: "Invalid connection configuration.",
+        ErrorCategory.UNKNOWN: "An unexpected error occurred.",
+    }
+    return messages.get(category, messages[ErrorCategory.UNKNOWN])
+
+
+def to_api_response(normalized: NormalizedError) -> dict:
+    """Convert NormalizedError to API response format."""
+    return {
+        "success": False,
+        "error": {
+            "category": normalized.category.value,
+            "message": normalized.message,
+            "next_steps": normalized.next_steps,
+            "field_hint": normalized.field_hint,
+            "details": normalized.original_error,
+        }
+    }

pymnemon-0.1.1.dist-info/METADATA

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: pymnemon
+Version: 0.1.1
+Summary: Unified db connector system with normalized error handling across multiple databases.
+Author-email: Causum <support@causum.com>
+Maintainer-email: Causum <support@causum.com>
+License: MIT License
+        
+        Copyright (c) 2026 The pymnemon contributors
+        
+        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.
+        
+Project-URL: Repository, https://gitlab.com/causum/mnemon
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: SQLAlchemy==2.0.45
+Requires-Dist: psycopg2-binary
+Requires-Dist: sqlalchemy-bigquery
+Requires-Dist: google-cloud-bigquery
+Requires-Dist: redshift-connector
+Requires-Dist: clickhouse-driver
+Requires-Dist: clickhouse-sqlalchemy>=0.3
+Requires-Dist: duckdb
+Requires-Dist: PyMySQL
+Requires-Dist: pyodbc
+Requires-Dist: databricks-sql-connector>=3.0
+Requires-Dist: trino
+Requires-Dist: PyHive
+Requires-Dist: vertica-python
+Requires-Dist: oracledb
+Requires-Dist: teradatasql
+Requires-Dist: ibm-db
+Requires-Dist: ibm-db-sa
+Requires-Dist: snowflake-sqlalchemy
+Requires-Dist: google-cloud-bigquery-storage
+Requires-Dist: PyAthena[SQLAlchemy]
+Dynamic: license-file
+
+# pymnemon
+
+Unified SQLAlchemy connector with normalized error handling across multiple databases.
+
+Note: The PyPI package name is `pymnemon`, but the import name is `mnemon`.
+
+## Install
+
+```bash
+pip install pymnemon
+```
+
+## Quickstart
+
+```python
+from mnemon import SchemaDBConnection
+
+config = {
+    "database_type": "postgresql",
+    "auth_method": "password",
+    "connection": {
+        "user": "dbuser",
+        "password": "dbpass",
+        "host": "localhost",
+        "port": 5432,
+        "database": "analytics",
+        # optional
+        # "sslmode": "require",
+    },
+}
+
+with SchemaDBConnection(config) as db:
+    ok, engine, error = db.safe_connect()
+    if not ok:
+        print(error)
+    else:
+        rows = db.execute_query("SELECT 1 AS ok")
+        print(rows)
+```
+
+## Configuration
+
+`SchemaDBConnection` expects a config dict with this shape:
+
+```python
+{
+  "database_type": "<supported database>",
+  "auth_method": "<supported auth method>",
+  "connection": { ... database-specific fields ... }
+}
+```
+
+Supported databases and auth methods:
+
+- postgresql: password, scram, ssl_verify, ssl_cert
+- mysql: password, ssl_verify, ssl_cert
+- mariadb: password, ssl_verify, ssl_cert
+- clickhouse: password, ssl_verify, ssl_cert
+- sqlserver: password
+- trino: none, password, jwt, certificate
+- sparksql: none, password, ldap
+- vertica: password, ldap, ssl_verify
+- oracle: password, wallet
+- teradata: password, ldap
+- db2: password, ldap
+- snowflake: password, key_pair
+- bigquery: service_account
+- redshift: password, iam_role
+- duckdb: local_file, motherduck
+- databricks: token, oauth_m2m
+- athena: iam_credentials
+
+### Example configs
+
+PostgreSQL (password):
+
+```python
+{
+  "database_type": "postgresql",
+  "auth_method": "password",
+  "connection": {
+    "user": "dbuser",
+    "password": "dbpass",
+    "host": "localhost",
+    "port": 5432,
+    "database": "analytics"
+  }
+}
+```
+
+Snowflake (key pair):
+
+```python
+{
+  "database_type": "snowflake",
+  "auth_method": "key_pair",
+  "connection": {
+    "account": "xy12345.us-east-1",
+    "user": "DBUSER",
+    "warehouse": "COMPUTE_WH",
+    "database": "ANALYTICS",
+    "schema": "PUBLIC",
+    "private_key": {"content": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"},
+    "private_key_passphrase": "optional"
+  }
+}
+```
+
+BigQuery (service account):
+
+```python
+{
+  "database_type": "bigquery",
+  "auth_method": "service_account",
+  "connection": {
+    "project": "my-gcp-project",
+    "dataset": "analytics",
+    "location": "US",
+    "credentials_json": {"content": "{... service account json ...}"}
+  }
+}
+```
+
+Databricks (PAT):
+
+```python
+{
+  "database_type": "databricks",
+  "auth_method": "token",
+  "connection": {
+    "host": "adb-1234567890.12.azuredatabricks.net",
+    "http_path": "/sql/1.0/warehouses/abcd1234",
+    "access_token": "dapi..."
+  }
+}
+```
+
+## Error handling
+
+`safe_connect()` returns `(success, engine, error)` where `error` is a normalized JSON payload with:
+
+```json
+{
+  "success": false,
+  "error": {
+    "category": "auth_failed",
+    "message": "Authentication failed. Please check your credentials.",
+    "next_steps": ["Verify username and password"],
+    "field_hint": "user or password",
+    "details": "... original error ..."
+  }
+}
+```
+
+## Notes on dependencies
+
+Some drivers require system dependencies or extra setup:
+
+- `pyodbc` for SQL Server requires an ODBC driver (e.g., ODBC Driver 18).
+- `oracledb` may require Oracle client configuration depending on mode.
+- `PyAthena[SQLAlchemy]` is used for Athena SQLAlchemy dialect support.
+
+## License
+
+MIT

pymnemon-0.1.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+mnemon/__init__.py,sha256=cqCaWE6LJSQwJ_UFGe_eDMNxv5SKB8wfwBvKeFcjb_k,154
+mnemon/db_connect.py,sha256=9AwOXhtURcl6aSyInIFQu7D9GlE1ks7mlhOUpqMjMXA,26264
+mnemon/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mnemon/utils/databricks_engine.py,sha256=tAmZxSkihn_YY3itAAlvqfJD7QMctbYfufYpE-xjSYw,5332
+mnemon/utils/dialect_queries.py,sha256=BCAC83UX7bnnUNc-NimiiLCbx98c4Wbakh39p1FKJxo,13740
+mnemon/utils/error_handling.py,sha256=QbsZ3S7pnjF5vMwmz2TAg3Zlrg4HwKT9HzwMDUa4Z_0,9375
+pymnemon-0.1.1.dist-info/licenses/LICENSE,sha256=15QLuwn7sTjGUIFYvN4UOhGRgd-goVM6L5BV3a-dioI,1082
+pymnemon-0.1.1.dist-info/METADATA,sha256=8JQK0WehCgBXihJq4R1hzXlJGLzsJ-UM2kP2AZR3dHo,5881
+pymnemon-0.1.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+pymnemon-0.1.1.dist-info/top_level.txt,sha256=gdVWuvUbAYZHDK1-Uav9qGngx7utfne-k5ixROarUHQ,7
+pymnemon-0.1.1.dist-info/RECORD,,

pymnemon-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pymnemon-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The pymnemon contributors
+
+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.

pymnemon-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+mnemon