fullscript.spellbook 2.1.6__tar.gz → 2.2.0__tar.gz

fullscript_spellbook-2.2.0/.gitignore

@@ -0,0 +1,9 @@
+*.whl
+*.egg-info
+*.tar.gz
+__pycache__/
+.pytest_cache/
+.idea/
+venv/
+/.junie/
+.DS_Store

{fullscript_spellbook-2.1.6 → fullscript_spellbook-2.2.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: fullscript.spellbook
-Version: 2.1.6
+Version: 2.2.0
 Summary: A simple package to make your life easier.
-Author-email: Thomas Edwards <thomas.edwards@fullscript.com>, Gui Chagas <gui.chagas@fullscript.com>, David King <david.king@fullscript.com>, Meinhard Mare <meinhard.mare@fullscript.com>, Karsten Melchers <karsten.melchers@fullscript.com>
+Author-email: Meinhard Mare <meinhard.mare@fullscript.com>, Thomas Edwards <thomas.edwards@fullscript.com>, Gui Chagas <gui.chagas@fullscript.com>, David King <david.king@fullscript.com>, Karsten Melchers <karsten.melchers@fullscript.com>
 License: MIT
 Project-URL: homepage, https://github.com/Fullscript/spellbook
 Requires-Python: <3.12,>=3.10
@@ -46,6 +46,7 @@ Requires-Dist: pycparser==2.22
 Requires-Dist: Pygments==2.18.0
 Requires-Dist: PyJWT==2.9.0
 Requires-Dist: pyOpenSSL==24.2.1
+Requires-Dist: PyMySQL==1.2.3
 Requires-Dist: python-dateutil==2.9.0.post0
 Requires-Dist: pytz==2024.2
 Requires-Dist: PyYAML==6.0.2
@@ -116,6 +117,8 @@ Requires-Dist: scipy==1.14.1; extra == "statsmagic"
 Requires-Dist: seaborn==0.13.2; extra == "statsmagic"
 Requires-Dist: six==1.16.0; extra == "statsmagic"
 Requires-Dist: statsmodels==0.14.4; extra == "statsmagic"
+Provides-Extra: test
+Requires-Dist: pytest==8.3.4; extra == "test"
 Dynamic: license-file
 
 # Spellbook
@@ -159,7 +162,7 @@ Spellbook requires Python 3.11 or higher. Use the following steps to install:
 1. Pip install:
 
 ```bash
-pip install git+https://git.fullscript.io/data/spellbook.git
+pip install fullscript.spellbook
 ```
 
 ## Configuration
@@ -186,6 +189,16 @@ databases:
     database: snowflake_database
     schema: snowflake_schema
 
+  # MySQL Database Connection using AWS RDS IAM authentication (no stored password).
+  # Fullscript internal only: requires the `rx` CLI. See documentation/db_magic.md.
+  - name: alias_of_your_connection
+    type: mysql
+    host: your_host.rds.amazonaws.com
+    port: 3306
+    user: ${DB_USER}
+    iam_auth: true
+    database: ${MYSQL_DATABASE}
+
 google_accounts:
   # Google Sheets Service Account 1
   - name: google_sheets_service_account_1

{fullscript_spellbook-2.1.6 → fullscript_spellbook-2.2.0}/README.md

@@ -39,7 +39,7 @@ Spellbook requires Python 3.11 or higher. Use the following steps to install:
 1. Pip install:
 
 ```bash
-pip install git+https://git.fullscript.io/data/spellbook.git
+pip install fullscript.spellbook
 ```
 
 ## Configuration
@@ -66,6 +66,16 @@ databases:
     database: snowflake_database
     schema: snowflake_schema
 
+  # MySQL Database Connection using AWS RDS IAM authentication (no stored password).
+  # Fullscript internal only: requires the `rx` CLI. See documentation/db_magic.md.
+  - name: alias_of_your_connection
+    type: mysql
+    host: your_host.rds.amazonaws.com
+    port: 3306
+    user: ${DB_USER}
+    iam_auth: true
+    database: ${MYSQL_DATABASE}
+
 google_accounts:
   # Google Sheets Service Account 1
   - name: google_sheets_service_account_1

{fullscript_spellbook-2.1.6 → fullscript_spellbook-2.2.0}/documentation/db_magic.md

@@ -10,6 +10,69 @@ A magical wrapper to perform work with databases.
 from spellbook import db_magic
 ```
 
+### MySQL Authentication
+
+MySQL connections support two authentication methods, chosen per database in `spellbook_config.yaml`.
+
+**Password authentication** is the default and needs no changes to an existing config:
+
+```yaml
+- name: legacy_mysql
+  type: mysql
+  host: your_host
+  port: 3306
+  user: mysql_user_name
+  password: ${MYSQL_PASSWORD}
+  database: mysql_database
+```
+
+**AWS RDS IAM authentication** stores no password at all. Add `iam_auth: true` and Spellbook
+calls `rx rds password <rds_db_name>` for a temporary token each time it connects, because the
+tokens expire after about 15 minutes:
+
+> **Internal use only.** `iam_auth` depends on the `rx` CLI, which is Fullscript internal
+> tooling and is not publicly available. Password authentication is the only MySQL option
+> outside Fullscript, and it remains fully supported.
+
+```yaml
+- name: reporting_db
+  type: mysql
+  host: ${MYSQL_HOST} # e.g. your-instance.abc123.us-east-1.rds.amazonaws.com
+  port: 3306
+  user: ${DB_USER}
+  iam_auth: true
+  rds_db_name: your_rds_instance_name # Optional, defaults to the value of `name`
+  database: ${MYSQL_DATABASE}
+```
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `iam_auth` | No | `true` switches the database to IAM tokens. Omitting it keeps password authentication. |
+| `user` | Yes | Your IAM database user. |
+| `rds_db_name` | No | The remote database as named by `rx rds list`. Defaults to `name`, so set it whenever your config alias differs from the RDS name. |
+| `ssl_ca` | No | Not needed in normal use; see below. |
+| `password` | No | Ignored when `iam_auth` is true. |
+
+Requirements for the IAM path:
+* The `rx` CLI must be installed and on your `PATH`.
+* You must be signed in to AWS. If a connection hangs or fails on authentication, run
+  `rx rds password <rds_db_name>` in a terminal once to complete the AWS SSO prompt.
+* IAM connections use the `pymysql` driver (installed with Spellbook). Password connections
+  continue to use `mysql-connector`.
+
+##### A note on TLS and `ssl_ca`
+
+AWS requires TLS for IAM authentication, so Spellbook always negotiates an encrypted
+connection. You do **not** need to set `ssl_ca` — leave it out and you get TLS without
+verifying which server you reached, which is the normal setup.
+
+Set `ssl_ca` only if you also want the server certificate verified. If you do:
+* Point it at the [AWS RDS CA bundle](https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem).
+  Your operating system's bundle will not work, because RDS certificates do not chain to a
+  publicly trusted root; using it fails with `CERTIFICATE_VERIFY_FAILED`.
+* Use the instance's own RDS endpoint as `host`. Verification also checks the hostname, so a
+  CNAME that points at the instance is likely to be rejected even with the right bundle.
+
 ### Methods Overview
 
 
@@ -95,4 +158,4 @@ update_query = "UPDATE users SET is_active = 1 WHERE last_login > '2024-01-01';"
 db_magic.run_sql("mysql_db", update_query)
 
 print("SQL executed successfully!")
-```
+```

{fullscript_spellbook-2.1.6 → fullscript_spellbook-2.2.0}/fullscript.spellbook.egg-info/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: fullscript.spellbook
-Version: 2.1.6
+Version: 2.2.0
 Summary: A simple package to make your life easier.
-Author-email: Thomas Edwards <thomas.edwards@fullscript.com>, Gui Chagas <gui.chagas@fullscript.com>, David King <david.king@fullscript.com>, Meinhard Mare <meinhard.mare@fullscript.com>, Karsten Melchers <karsten.melchers@fullscript.com>
+Author-email: Meinhard Mare <meinhard.mare@fullscript.com>, Thomas Edwards <thomas.edwards@fullscript.com>, Gui Chagas <gui.chagas@fullscript.com>, David King <david.king@fullscript.com>, Karsten Melchers <karsten.melchers@fullscript.com>
 License: MIT
 Project-URL: homepage, https://github.com/Fullscript/spellbook
 Requires-Python: <3.12,>=3.10
@@ -46,6 +46,7 @@ Requires-Dist: pycparser==2.22
 Requires-Dist: Pygments==2.18.0
 Requires-Dist: PyJWT==2.9.0
 Requires-Dist: pyOpenSSL==24.2.1
+Requires-Dist: PyMySQL==1.2.3
 Requires-Dist: python-dateutil==2.9.0.post0
 Requires-Dist: pytz==2024.2
 Requires-Dist: PyYAML==6.0.2
@@ -116,6 +117,8 @@ Requires-Dist: scipy==1.14.1; extra == "statsmagic"
 Requires-Dist: seaborn==0.13.2; extra == "statsmagic"
 Requires-Dist: six==1.16.0; extra == "statsmagic"
 Requires-Dist: statsmodels==0.14.4; extra == "statsmagic"
+Provides-Extra: test
+Requires-Dist: pytest==8.3.4; extra == "test"
 Dynamic: license-file
 
 # Spellbook
@@ -159,7 +162,7 @@ Spellbook requires Python 3.11 or higher. Use the following steps to install:
 1. Pip install:
 
 ```bash
-pip install git+https://git.fullscript.io/data/spellbook.git
+pip install fullscript.spellbook
 ```
 
 ## Configuration
@@ -186,6 +189,16 @@ databases:
     database: snowflake_database
     schema: snowflake_schema
 
+  # MySQL Database Connection using AWS RDS IAM authentication (no stored password).
+  # Fullscript internal only: requires the `rx` CLI. See documentation/db_magic.md.
+  - name: alias_of_your_connection
+    type: mysql
+    host: your_host.rds.amazonaws.com
+    port: 3306
+    user: ${DB_USER}
+    iam_auth: true
+    database: ${MYSQL_DATABASE}
+
 google_accounts:
   # Google Sheets Service Account 1
   - name: google_sheets_service_account_1

{fullscript_spellbook-2.1.6 → fullscript_spellbook-2.2.0}/fullscript.spellbook.egg-info/SOURCES.txt

@@ -1,4 +1,3 @@
-.DS_Store
 .gitignore
 .gitlab-ci.yml
 .python-version
@@ -17,8 +16,9 @@ fullscript.spellbook.egg-info/PKG-INFO
 fullscript.spellbook.egg-info/SOURCES.txt
 fullscript.spellbook.egg-info/dependency_links.txt
 fullscript.spellbook.egg-info/requires.txt
+fullscript.spellbook.egg-info/scm_file_list.json
+fullscript.spellbook.egg-info/scm_version.json
 fullscript.spellbook.egg-info/top_level.txt
-spellbook/.DS_Store
 spellbook/__init__.py
 spellbook/db_magic.py
 spellbook/drive_magic.py
@@ -37,4 +37,5 @@ spellbook/wizards/wizard5.txt
 spellbook/wizards/wizard6.txt
 spellbook/wizards/wizard7.txt
 spellbook/wizards/wizard8.txt
-spellbook/wizards/wizard9.txt
+spellbook/wizards/wizard9.txt
+tests/test_db_magic.py

{fullscript_spellbook-2.1.6 → fullscript_spellbook-2.2.0}/fullscript.spellbook.egg-info/requires.txt

@@ -36,6 +36,7 @@ pycparser==2.22
 Pygments==2.18.0
 PyJWT==2.9.0
 pyOpenSSL==24.2.1
+PyMySQL==1.2.3
 python-dateutil==2.9.0.post0
 pytz==2024.2
 PyYAML==6.0.2
@@ -109,3 +110,6 @@ scipy==1.14.1
 seaborn==0.13.2
 six==1.16.0
 statsmodels==0.14.4
+
+[test]
+pytest==8.3.4

fullscript_spellbook-2.2.0/fullscript.spellbook.egg-info/scm_file_list.json

@@ -0,0 +1,38 @@
+{
+  "files": [
+    ".gitignore",
+    ".gitlab-ci.yml",
+    ".python-version",
+    "LICENSE",
+    "MANIFEST.in",
+    "README.md",
+    "documentation/db_magic.md",
+    "documentation/drive_magic.md",
+    "documentation/sheet_magic.md",
+    "documentation/snowflake_key_pair_setup.md",
+    "documentation/stats_magic.md",
+    "pyproject.toml",
+    "requirements.txt",
+    "spellbook/__init__.py",
+    "spellbook/db_magic.py",
+    "spellbook/drive_magic.py",
+    "spellbook/sheet_magic.py",
+    "spellbook/stats_magic.py",
+    "spellbook/utils.py",
+    "spellbook/wizards/__init__.py",
+    "spellbook/wizards/wizard1.txt",
+    "spellbook/wizards/wizard10.txt",
+    "spellbook/wizards/wizard11.txt",
+    "spellbook/wizards/wizard12.txt",
+    "spellbook/wizards/wizard2.txt",
+    "spellbook/wizards/wizard3.txt",
+    "spellbook/wizards/wizard4.txt",
+    "spellbook/wizards/wizard5.txt",
+    "spellbook/wizards/wizard6.txt",
+    "spellbook/wizards/wizard7.txt",
+    "spellbook/wizards/wizard8.txt",
+    "spellbook/wizards/wizard9.txt",
+    "spellbook_config.yaml",
+    "tests/test_db_magic.py"
+  ]
+}

fullscript_spellbook-2.2.0/fullscript.spellbook.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "2.2.0",
+  "distance": 0,
+  "node": "gb79ed51cfa3c9db792124b375e8edb615250590b",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-22"
+}

{fullscript_spellbook-2.1.6 → fullscript_spellbook-2.2.0}/pyproject.toml

@@ -10,10 +10,10 @@ readme = "README.md"
 license = {text = "MIT"}
 requires-python = ">=3.10, <3.12"
 authors = [
+    {name = "Meinhard Mare", email = "meinhard.mare@fullscript.com"},
     {name = "Thomas Edwards", email = "thomas.edwards@fullscript.com"},
     {name = "Gui Chagas", email = "gui.chagas@fullscript.com"},
     {name = "David King", email = "david.king@fullscript.com"},
-    {name = "Meinhard Mare", email = "meinhard.mare@fullscript.com"},
     {name = "Karsten Melchers", email = "karsten.melchers@fullscript.com"}
 ]
 urls = {homepage = "https://github.com/Fullscript/spellbook"}
@@ -56,6 +56,7 @@ dependencies = [
     "Pygments==2.18.0",
     "PyJWT==2.9.0",
     "pyOpenSSL==24.2.1",
+    "PyMySQL==1.2.3",
     "python-dateutil==2.9.0.post0",
     "pytz==2024.2",
     "PyYAML==6.0.2",
@@ -133,6 +134,13 @@ statsmagic = [
     "statsmodels==0.14.4"
 ]
 
+test = [
+    "pytest==8.3.4"
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["spellbook"]

{fullscript_spellbook-2.1.6 → fullscript_spellbook-2.2.0}/requirements.txt

@@ -183,14 +183,14 @@ six==1.16.0
     #   asttokens
     #   fullscript.spellbook (pyproject.toml)
     #   python-dateutil
-snowflake-connector-python==3.15.0
+snowflake-connector-python==4.2.0
     # via
     #   fullscript.spellbook (pyproject.toml)
     #   snowflake-snowpark-python
     #   snowflake-sqlalchemy
-snowflake-snowpark-python==1.25.0
+snowflake-snowpark-python==1.44.0
     # via fullscript.spellbook (pyproject.toml)
-snowflake-sqlalchemy==1.7.0
+snowflake-sqlalchemy==1.8.2
     # via fullscript.spellbook (pyproject.toml)
 sortedcontainers==2.4.0
     # via

{fullscript_spellbook-2.1.6 → fullscript_spellbook-2.2.0}/spellbook/db_magic.py

@@ -1,16 +1,38 @@
 import os
+import re
+import subprocess
 from snowflake.snowpark import Session
 from sqlalchemy import create_engine
 import pandas as pd
 from cryptography.hazmat.backends import default_backend
 from cryptography.hazmat.primitives import serialization
 import base64
+from urllib.parse import quote_plus
 from spellbook.utils import load_and_parse_config, get_wizard, load_sql_file
 
 
 # Needs a very specific pip install
 # pip install "snowflake-connector-python[pandas]"
 
+# How long to wait for `rx` to mint an RDS IAM token. The first call of the day can
+# be slow because `rx` has to walk through AWS SSO before it reaches RDS.
+RDS_TOKEN_TIMEOUT = 120
+
+# `rx` colourises its progress output, which has to come off before we can read the token.
+_ANSI_ESCAPE = re.compile(r'\x1b\[[0-9;]*[a-zA-Z]')
+
+# Built on first use so that pymysql is only imported when an IAM connection is made.
+_IAM_CURSOR_CLASS = None
+
+
+def _strip_ansi(text):
+    """
+    Remove ANSI colour and cursor codes from CLI output.
+    :param text: The raw text written by the CLI.
+    :return: The same text with escape codes removed.
+    """
+    return _ANSI_ESCAPE.sub('', text or '')
+
 
 def get_db_config(db_name):
     # load the configuration
@@ -82,18 +104,126 @@ def snowflake_connect(db_name, **kwargs):
         return None
 
 
+def _iam_cursor_class():
+    """
+    Build the pymysql cursor used for IAM connections.
+
+    pymysql substitutes parameters whenever `args is not None`, so the empty parameter set
+    pandas passes turns a `like '%value%'` clause into a format string and raises
+    "unsupported format character". mysql-connector guards on `if params:` instead, which
+    leaves such queries alone, so this keeps both drivers behaving the same way.
+
+    :return: A pymysql cursor class that treats an empty parameter set as no parameters.
+    """
+    global _IAM_CURSOR_CLASS
+    if _IAM_CURSOR_CLASS is None:
+        import pymysql.cursors
+
+        class LiteralPercentCursor(pymysql.cursors.Cursor):
+            def execute(self, query, args=None):
+                return super().execute(query, args if args else None)
+
+        _IAM_CURSOR_CLASS = LiteralPercentCursor
+    return _IAM_CURSOR_CLASS
+
+
+def get_rds_iam_token(rds_db_name, timeout=RDS_TOKEN_TIMEOUT):
+    """
+    Generate a temporary AWS RDS IAM authentication token using the `rx` CLI.
+
+    The token stands in for a stored password and expires after about 15 minutes, so it
+    has to be fetched fresh for every connection rather than cached in the config file.
+
+    :param rds_db_name: The remote database name, as listed by `rx rds list`.
+    :param timeout: Seconds to wait for `rx` before giving up.
+    :return: The token to use as the connection password.
+    :raises RuntimeError: If `rx` is unavailable, times out, fails, or returns no token.
+    """
+    command = ['rx', 'rds', 'password', rds_db_name]
+    printable = ' '.join(command)
+
+    try:
+        result = subprocess.run(command, capture_output=True, text=True, timeout=timeout)
+    except FileNotFoundError:
+        raise RuntimeError(
+            "AWS RDS IAM authentication failed: the 'rx' command is not installed or not on "
+            "your PATH. Install the Fullscript developer tooling, or drop 'iam_auth' from the "
+            "database configuration to go back to password authentication."
+        ) from None
+    except subprocess.TimeoutExpired:
+        raise RuntimeError(
+            f"AWS RDS IAM authentication failed: '{printable}' did not finish within {timeout} "
+            f"seconds. It is probably waiting on AWS SSO - run '{printable}' in a terminal once "
+            "to sign in, then try again."
+        ) from None
+
+    if result.returncode != 0:
+        detail = _strip_ansi(result.stderr or result.stdout or '').strip()
+        raise RuntimeError(
+            f"AWS RDS IAM authentication failed: '{printable}' exited with status "
+            f"{result.returncode}. Check that '{rds_db_name}' appears in 'rx rds list' and that "
+            f"you are signed in to AWS. Output from rx: {detail or '<none>'}"
+        )
+
+    # `rx` writes progress lines before the token, so the token is the last thing it prints.
+    lines = [line.strip() for line in _strip_ansi(result.stdout).splitlines() if line.strip()]
+    if not lines:
+        raise RuntimeError(
+            f"AWS RDS IAM authentication failed: '{printable}' succeeded but returned no token."
+        )
+
+    return lines[-1]
+
+
 def mysql_connect(db_name, **kwargs):
+    """
+    Create a MySQL connection using either AWS RDS IAM authentication or a stored password.
+
+    Set `iam_auth: true` on the database in the config file to authenticate with a temporary
+    IAM token from `rx rds password`. Without it, the `password` field is used as before.
+
+    :param db_name: The name of the database as defined in the config file.
+    :return: SQLAlchemy connection object, or None if the connection could not be made.
+    """
     db_config = get_db_config(db_name, **kwargs)
     try:
-        connection_string = (
-            f"mysql+mysqlconnector://{db_config['user']}:{db_config['password']}"
-            f"@{db_config['host']}:{db_config.get('port', 3306)}/{db_config['database']}"
-        )
-        engine = create_engine(connection_string)
+        host = db_config['host']
+        port = db_config.get('port', 3306)
+        database = db_config['database']
+
+        if db_config.get('iam_auth'):
+            # RDS instance names rarely match the alias used in the config file, so allow an
+            # override and fall back to the alias when the two happen to line up.
+            token = get_rds_iam_token(db_config.get('rds_db_name', db_config['name']))
+            # IAM tokens are URL shaped, so they have to be escaped inside the connection
+            # string. AWS also requires TLS, and only pymysql completes the token handshake.
+            ssl_ca = db_config.get('ssl_ca')
+            connection_string = (
+                f"mysql+pymysql://{quote_plus(db_config['user'])}:{quote_plus(token)}"
+                f"@{host}:{port}/{database}"
+            )
+            # A CA bundle gets the certificate verified too; without one we still insist on
+            # an encrypted connection, we just cannot prove who is on the other end.
+            connect_args = {
+                'ssl': {'ca': ssl_ca} if ssl_ca else {'check_hostname': False},
+                'cursorclass': _iam_cursor_class(),
+            }
+        else:
+            connection_string = (
+                f"mysql+mysqlconnector://{db_config['user']}:{db_config['password']}"
+                f"@{host}:{port}/{database}"
+            )
+            connect_args = {}
+
+        engine = create_engine(connection_string, connect_args=connect_args)
         con = engine.connect()
         return con
     except Exception as e:
-        print(f"An error occurred creating the MySQL connection: {e}")
+        auth_method = 'AWS RDS IAM' if db_config.get('iam_auth') else 'password'
+        print(
+            f"An error occurred creating the MySQL connection to '{db_name}' "
+            f"using {auth_method} authentication: {e}"
+        )
         return None
 
 

{fullscript_spellbook-2.1.6 → fullscript_spellbook-2.2.0}/spellbook_config.yaml

@@ -33,6 +33,17 @@ databases:
     password: mysql_password
     database: mysql_database
 
+  # MySQL Database Connection using AWS RDS IAM authentication.
+  # Requires the `rx` CLI, which is Fullscript internal tooling.
+  - name: alias_of_your_connection_3
+    type: mysql
+    host: ${MYSQL_HOST} # e.g. your-instance.abc123.us-east-1.rds.amazonaws.com
+    port: 3306
+    user: ${DB_USER} # Your IAM database user
+    iam_auth: true # Use an AWS RDS IAM token instead of a password
+    rds_db_name: your_rds_instance_name # Optional, as named by `rx rds list`; defaults to `name`
+    database: ${MYSQL_DATABASE}
+
 google_accounts:
   # Google Sheets Service Account 1
   - name: google_sheets_service_account_1

fullscript_spellbook-2.2.0/tests/test_db_magic.py

@@ -0,0 +1,316 @@
+import subprocess
+
+import pytest
+
+from spellbook import db_magic
+
+
+PASSWORD_DB = {
+    'name': 'legacy_mysql',
+    'type': 'mysql',
+    'host': 'legacy.example.com',
+    'port': 3306,
+    'user': 'mysql_user_name',
+    'password': 'mysql_password',
+    'database': 'mysql_database',
+}
+
+IAM_DB = {
+    'name': 'reporting_db',
+    'type': 'mysql',
+    'host': 'example-db.abc123.us-east-1.rds.amazonaws.com',
+    'port': 3306,
+    'user': 'iam_user',
+    'iam_auth': True,
+    'rds_db_name': 'example-rds-instance',
+    'database': 'mysql_database',
+}
+
+# Real IAM tokens are URL shaped: the query string has to survive the trip into the
+# connection string without being mistaken for part of the URL.
+FAKE_TOKEN = (
+    'example-db.abc123.us-east-1.rds.amazonaws.com:3306/'
+    '?Action=connect&DBUser=iam_user&X-Amz-Signature=abc123'
+)
+
+
+@pytest.fixture
+def engines(monkeypatch):
+    """Capture the arguments mysql_connect passes to create_engine."""
+    calls = []
+
+    class FakeEngine:
+        def connect(self):
+            return 'connection'
+
+    def fake_create_engine(connection_string, **kwargs):
+        calls.append((connection_string, kwargs))
+        return FakeEngine()
+
+    monkeypatch.setattr(db_magic, 'create_engine', fake_create_engine)
+    return calls
+
+
+@pytest.fixture
+def config(monkeypatch):
+    """Point get_db_config at an in-test database list."""
+    def use(*databases):
+        by_name = {db['name']: db for db in databases}
+        monkeypatch.setattr(db_magic, 'get_db_config', lambda name, **kwargs: by_name[name])
+    return use
+
+
+def fake_rx(stdout='', stderr='', returncode=0, expect=None, raises=None):
+    """Build a stand-in for subprocess.run that mimics one `rx rds password` outcome."""
+    def run(command, **kwargs):
+        if expect is not None:
+            assert command == expect
+        if raises is not None:
+            raise raises
+        return subprocess.CompletedProcess(command, returncode, stdout=stdout, stderr=stderr)
+    return run
+
+
+# --- Password authentication stays exactly as it was -------------------------------------
+
+def test_password_auth_uses_mysqlconnector(monkeypatch, config, engines):
+    config(PASSWORD_DB)
+    # Any attempt to shell out to rx on the password path is a backward compatibility bug.
+    monkeypatch.setattr(subprocess, 'run', fake_rx(raises=AssertionError('rx must not run')))
+
+    con = db_magic.mysql_connect('legacy_mysql')
+
+    assert con == 'connection'
+    connection_string, kwargs = engines[0]
+    assert connection_string == (
+        'mysql+mysqlconnector://mysql_user_name:mysql_password'
+        '@legacy.example.com:3306/mysql_database'
+    )
+    assert kwargs == {'connect_args': {}}
+
+
+def test_password_auth_defaults_the_port(config, engines):
+    config({key: value for key, value in PASSWORD_DB.items() if key != 'port'})
+
+    db_magic.mysql_connect('legacy_mysql')
+
+    assert ':3306/' in engines[0][0]
+
+
+def test_iam_auth_false_behaves_like_password_auth(config, engines):
+    config({**PASSWORD_DB, 'iam_auth': False})
+
+    db_magic.mysql_connect('legacy_mysql')
+
+    assert engines[0][0].startswith('mysql+mysqlconnector://')
+
+
+# --- IAM authentication ------------------------------------------------------------------
+
+def test_iam_auth_builds_a_pymysql_connection_string(monkeypatch, config, engines):
+    config(IAM_DB)
+    monkeypatch.setattr(subprocess, 'run', fake_rx(
+        stdout=FAKE_TOKEN + '\n',
+        expect=['rx', 'rds', 'password', 'example-rds-instance'],
+    ))
+
+    con = db_magic.mysql_connect('reporting_db')
+
+    assert con == 'connection'
+    connection_string, kwargs = engines[0]
+    assert connection_string.startswith('mysql+pymysql://iam_user:')
+    assert connection_string.endswith(
+        '@example-db.abc123.us-east-1.rds.amazonaws.com:3306/mysql_database'
+    )
+    # The token's own '?' and '&' must be escaped, or SQLAlchemy reads them as URL structure.
+    assert '?Action=connect' not in connection_string
+    assert '%3FAction%3Dconnect' in connection_string
+    # TLS is mandatory for RDS IAM, so the ssl options must be truthy for pymysql to require it.
+    assert kwargs['connect_args']['ssl']
+
+
+def test_iam_auth_connection_string_round_trips_the_token(monkeypatch, config, engines):
+    from sqlalchemy.engine import make_url
+
+    config(IAM_DB)
+    monkeypatch.setattr(subprocess, 'run', fake_rx(stdout=FAKE_TOKEN))
+
+    db_magic.mysql_connect('reporting_db')
+
+    url = make_url(engines[0][0])
+    assert url.password == FAKE_TOKEN
+    assert url.username == 'iam_user'
+    assert url.database == 'mysql_database'
+
+
+def test_iam_auth_falls_back_to_the_config_alias_for_the_rds_name(monkeypatch, config, engines):
+    without_override = {key: value for key, value in IAM_DB.items() if key != 'rds_db_name'}
+    config(without_override)
+    monkeypatch.setattr(subprocess, 'run', fake_rx(
+        stdout=FAKE_TOKEN,
+        expect=['rx', 'rds', 'password', 'reporting_db'],
+    ))
+
+    assert db_magic.mysql_connect('reporting_db') == 'connection'
+
+
+def test_iam_auth_verifies_the_certificate_when_a_ca_bundle_is_given(monkeypatch, config, engines):
+    config({**IAM_DB, 'ssl_ca': '/certs/rds-ca.pem'})
+    monkeypatch.setattr(subprocess, 'run', fake_rx(stdout=FAKE_TOKEN))
+
+    db_magic.mysql_connect('reporting_db')
+
+    assert engines[0][1]['connect_args']['ssl'] == {'ca': '/certs/rds-ca.pem'}
+
+
+def test_iam_auth_requires_tls_without_a_ca_bundle(monkeypatch, config, engines):
+    config(IAM_DB)
+    monkeypatch.setattr(subprocess, 'run', fake_rx(stdout=FAKE_TOKEN))
+
+    db_magic.mysql_connect('reporting_db')
+
+    assert engines[0][1]['connect_args']['ssl'] == {'check_hostname': False}
+
+
+def test_iam_auth_fetches_a_fresh_token_per_connection(monkeypatch, config, engines):
+    config(IAM_DB)
+    tokens = iter(['token-one', 'token-two'])
+    monkeypatch.setattr(
+        subprocess, 'run',
+        lambda command, **kwargs: subprocess.CompletedProcess(
+            command, 0, stdout=next(tokens), stderr=''
+        ),
+    )
+
+    db_magic.mysql_connect('reporting_db')
+    db_magic.mysql_connect('reporting_db')
+
+    assert 'token-one' in engines[0][0]
+    assert 'token-two' in engines[1][0]
+
+
+# --- Literal '%' must survive on the pymysql path ----------------------------------------
+# pymysql substitutes whenever args is not None, so the empty parameter set pandas passes
+# would turn `like '%x%'` into a format string. mysql-connector guards on `if params:`,
+# so without this the IAM path would break queries the password path handles fine.
+
+def test_iam_auth_uses_a_cursor_that_leaves_literal_percent_alone(monkeypatch, config, engines):
+    config(IAM_DB)
+    monkeypatch.setattr(subprocess, 'run', fake_rx(stdout=FAKE_TOKEN))
+
+    db_magic.mysql_connect('reporting_db')
+
+    cursor_class = engines[0][1]['connect_args']['cursorclass']
+    import pymysql.cursors
+    assert issubclass(cursor_class, pymysql.cursors.Cursor)
+
+
+@pytest.fixture
+def iam_cursor(monkeypatch):
+    """An IAM cursor whose pymysql parent records the args it is handed."""
+    import pymysql.cursors
+
+    recorded = []
+    monkeypatch.setattr(
+        pymysql.cursors.Cursor, 'execute',
+        lambda self, query, args=None: recorded.append(args),
+    )
+    return db_magic._iam_cursor_class()(None), recorded
+
+
+@pytest.mark.parametrize('empty', [(), [], {}])
+def test_empty_parameters_reach_pymysql_as_none(iam_cursor, empty):
+    """An empty parameter set must arrive as None, or '%' gets read as a format character."""
+    cursor, recorded = iam_cursor
+
+    cursor.execute("select 1 from t where name like '%x%'", empty)
+
+    assert recorded == [None]
+
+
+def test_omitted_parameters_reach_pymysql_as_none(iam_cursor):
+    cursor, recorded = iam_cursor
+
+    cursor.execute("select 1 from t where name like '%x%'")
+
+    assert recorded == [None]
+
+
+def test_real_parameters_are_still_forwarded(iam_cursor):
+    cursor, recorded = iam_cursor
+
+    cursor.execute('select 1 from t where id = %s', (42,))
+
+    assert recorded == [(42,)]
+
+
+# --- Token retrieval ---------------------------------------------------------------------
+
+def test_token_is_read_from_the_last_line_of_noisy_output(monkeypatch):
+    monkeypatch.setattr(subprocess, 'run', fake_rx(
+        stdout='\x1b[32m⠿ Waiting for AWS authentication\x1b[0m\n\n' + FAKE_TOKEN + '\n',
+    ))
+
+    assert db_magic.get_rds_iam_token('example-rds-instance') == FAKE_TOKEN
+
+
+def test_missing_rx_raises_a_clear_error(monkeypatch):
+    monkeypatch.setattr(subprocess, 'run', fake_rx(raises=FileNotFoundError('rx')))
+
+    with pytest.raises(RuntimeError, match="'rx' command is not installed"):
+        db_magic.get_rds_iam_token('example-rds-instance')
+
+
+def test_rx_timeout_raises_a_clear_error(monkeypatch):
+    monkeypatch.setattr(subprocess, 'run', fake_rx(
+        raises=subprocess.TimeoutExpired(cmd='rx', timeout=120),
+    ))
+
+    with pytest.raises(RuntimeError, match='did not finish within'):
+        db_magic.get_rds_iam_token('example-rds-instance')
+
+
+def test_rx_failure_surfaces_its_output(monkeypatch):
+    monkeypatch.setattr(subprocess, 'run', fake_rx(
+        returncode=1, stderr='\x1b[;31m✘ database not found\x1b[;m',
+    ))
+
+    with pytest.raises(RuntimeError) as error:
+        db_magic.get_rds_iam_token('typo-db')
+
+    message = str(error.value)
+    assert 'exited with status 1' in message
+    assert '✘ database not found' in message
+    assert '\x1b' not in message  # colour codes stripped so the message stays readable
+    assert 'typo-db' in message
+
+
+def test_empty_rx_output_raises_rather_than_connecting_with_a_blank_password(monkeypatch):
+    monkeypatch.setattr(subprocess, 'run', fake_rx(stdout='   \n\n'))
+
+    with pytest.raises(RuntimeError, match='returned no token'):
+        db_magic.get_rds_iam_token('example-rds-instance')
+
+
+def test_iam_failure_reports_which_auth_method_failed(monkeypatch, config, capsys):
+    config(IAM_DB)
+    monkeypatch.setattr(subprocess, 'run', fake_rx(raises=FileNotFoundError('rx')))
+
+    assert db_magic.mysql_connect('reporting_db') is None
+
+    output = capsys.readouterr().out
+    assert 'AWS RDS IAM authentication' in output
+    assert 'reporting_db' in output
+
+
+def test_password_failure_reports_which_auth_method_failed(monkeypatch, config, capsys):
+    config(PASSWORD_DB)
+    monkeypatch.setattr(db_magic, 'create_engine', lambda *a, **k: (_ for _ in ()).throw(
+        RuntimeError('driver missing')
+    ))
+
+    assert db_magic.mysql_connect('legacy_mysql') is None
+
+    output = capsys.readouterr().out
+    assert 'password authentication' in output
+    assert 'driver missing' in output

fullscript_spellbook-2.1.6/.gitignore

@@ -1,3 +0,0 @@
-*.whl
-*.egg-info
-*.tar.gz