fullscript.spellbook 3.0.1__tar.gz → 3.0.2__tar.gz

{fullscript_spellbook-3.0.1 → fullscript_spellbook-3.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fullscript.spellbook
-Version: 3.0.1
+Version: 3.0.2
 Summary: A simple package to make your life easier.
 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
@@ -177,25 +177,34 @@ An example of the `spellbook_config.yaml` file is shown below:
 ```yaml
 databases:
   # Snowflake Database Connection
-  - name: alias_of_your_connection
+  - name: snowflake_example
     type: snowflake
-    account: your_account
-    user: snowflake_user_name # Optional for private key auth
-    password: snowflake_password # Optional, used if private key is not present
-    private_key: snowflake_pk # Base64-encoded private key
-    private_key_passphrase: snowflake_pk_phrase # Optional
+    account: ${SNOWFLAKE_ACCOUNT}
+    user: ${SNOWFLAKE_USER}
+    password: ${SNOWFLAKE_PASSWORD} # Optional when a private key is given
+    private_key: ${SNOW_PK} # Base64-encoded; used in preference to the password
+    private_key_passphrase: ${SNOW_PK_PASSPHRASE} # Optional
     role: snowflake_role
     warehouse: snowflake_warehouse
     database: snowflake_database
-    schema: snowflake_schema
+    schema: snowflake_schema # Optional, defaults to 'public'
+
+  # MySQL Database Connection using a stored password
+  - name: mysql_example
+    type: mysql
+    host: your_host
+    port: 3306
+    user: mysql_user_name
+    password: ${MYSQL_PASSWORD}
+    database: mysql_database
 
   # 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
+  # No `user` is needed - the IAM token names the user it was issued for.
+  - name: mysql_iam_example
     type: mysql
     host: your_host.rds.amazonaws.com
     port: 3306
-    user: ${DB_USER}
     iam_auth: true
     database: ${MYSQL_DATABASE}
 

{fullscript_spellbook-3.0.1 → fullscript_spellbook-3.0.2}/README.md

@@ -54,25 +54,34 @@ An example of the `spellbook_config.yaml` file is shown below:
 ```yaml
 databases:
   # Snowflake Database Connection
-  - name: alias_of_your_connection
+  - name: snowflake_example
     type: snowflake
-    account: your_account
-    user: snowflake_user_name # Optional for private key auth
-    password: snowflake_password # Optional, used if private key is not present
-    private_key: snowflake_pk # Base64-encoded private key
-    private_key_passphrase: snowflake_pk_phrase # Optional
+    account: ${SNOWFLAKE_ACCOUNT}
+    user: ${SNOWFLAKE_USER}
+    password: ${SNOWFLAKE_PASSWORD} # Optional when a private key is given
+    private_key: ${SNOW_PK} # Base64-encoded; used in preference to the password
+    private_key_passphrase: ${SNOW_PK_PASSPHRASE} # Optional
     role: snowflake_role
     warehouse: snowflake_warehouse
     database: snowflake_database
-    schema: snowflake_schema
+    schema: snowflake_schema # Optional, defaults to 'public'
+
+  # MySQL Database Connection using a stored password
+  - name: mysql_example
+    type: mysql
+    host: your_host
+    port: 3306
+    user: mysql_user_name
+    password: ${MYSQL_PASSWORD}
+    database: mysql_database
 
   # 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
+  # No `user` is needed - the IAM token names the user it was issued for.
+  - name: mysql_iam_example
     type: mysql
     host: your_host.rds.amazonaws.com
     port: 3306
-    user: ${DB_USER}
     iam_auth: true
     database: ${MYSQL_DATABASE}
 

{fullscript_spellbook-3.0.1 → fullscript_spellbook-3.0.2}/documentation/db_magic.md

@@ -81,16 +81,18 @@ tokens expire after about 15 minutes:
   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}
 ```
 
+No `user` is needed: the IAM token names the user it was issued for, and Spellbook reads it
+from the token. Set `user` only if you want to pin it, in which case it must match the token.
+
 | Field | Required | Notes |
 | --- | --- | --- |
 | `iam_auth` | No | `true` switches the database to IAM tokens. Omitting it keeps password authentication. |
-| `user` | Yes | Your IAM database user. |
+| `user` | No | Read from the token's `DBUser`. Set it only to pin a specific user; a value that disagrees with the token is reported as a config error. |
 | `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. |

{fullscript_spellbook-3.0.1 → fullscript_spellbook-3.0.2}/fullscript.spellbook.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fullscript.spellbook
-Version: 3.0.1
+Version: 3.0.2
 Summary: A simple package to make your life easier.
 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
@@ -177,25 +177,34 @@ An example of the `spellbook_config.yaml` file is shown below:
 ```yaml
 databases:
   # Snowflake Database Connection
-  - name: alias_of_your_connection
+  - name: snowflake_example
     type: snowflake
-    account: your_account
-    user: snowflake_user_name # Optional for private key auth
-    password: snowflake_password # Optional, used if private key is not present
-    private_key: snowflake_pk # Base64-encoded private key
-    private_key_passphrase: snowflake_pk_phrase # Optional
+    account: ${SNOWFLAKE_ACCOUNT}
+    user: ${SNOWFLAKE_USER}
+    password: ${SNOWFLAKE_PASSWORD} # Optional when a private key is given
+    private_key: ${SNOW_PK} # Base64-encoded; used in preference to the password
+    private_key_passphrase: ${SNOW_PK_PASSPHRASE} # Optional
     role: snowflake_role
     warehouse: snowflake_warehouse
     database: snowflake_database
-    schema: snowflake_schema
+    schema: snowflake_schema # Optional, defaults to 'public'
+
+  # MySQL Database Connection using a stored password
+  - name: mysql_example
+    type: mysql
+    host: your_host
+    port: 3306
+    user: mysql_user_name
+    password: ${MYSQL_PASSWORD}
+    database: mysql_database
 
   # 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
+  # No `user` is needed - the IAM token names the user it was issued for.
+  - name: mysql_iam_example
     type: mysql
     host: your_host.rds.amazonaws.com
     port: 3306
-    user: ${DB_USER}
     iam_auth: true
     database: ${MYSQL_DATABASE}
 

{fullscript_spellbook-3.0.1 → fullscript_spellbook-3.0.2}/fullscript.spellbook.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "3.0.1",
+  "tag": "3.0.2",
   "distance": 0,
-  "node": "g4c7e282904d3f4b9436cecd6265dbc228d36c8de",
+  "node": "gdb663ba3a57f8425421f12ce4d2b484ea72f5022",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-10-22"

{fullscript_spellbook-3.0.1 → fullscript_spellbook-3.0.2}/spellbook/db_magic.py

@@ -4,7 +4,7 @@ import os
 import re
 import subprocess
 from typing import Any
-from urllib.parse import quote_plus
+from urllib.parse import parse_qs, quote_plus
 
 import pandas as pd
 from cryptography.hazmat.backends import default_backend
@@ -49,13 +49,48 @@ SUPPORTED_DB_TYPES = ('snowflake', 'mysql')
 # Settings a connection genuinely cannot be made without, checked only for the database
 # being used. Anything absent from here is optional and may resolve to an empty value:
 # `private_key_passphrase`, `schema`, `port`, `ssl_ca` and `rds_db_name` all have defaults
-# or meaningful empty behaviour. MySQL also requires `password` unless `iam_auth` is set.
+# or meaningful empty behaviour. See required_fields() for the per-database adjustments.
 REQUIRED_FIELDS = {
     'mysql': ('host', 'user', 'database'),
     'snowflake': ('account', 'user', 'role', 'warehouse', 'database'),
 }
 
 
+def required_fields(db_config: dict[str, Any]) -> tuple[str, ...]:
+    """
+    Work out which settings this particular database cannot do without.
+
+    MySQL needs a `password` unless it authenticates with an IAM token, and conversely an
+    IAM database does not need a `user`, because the token says who it was issued to.
+
+    :param db_config: The configuration block for the database.
+    :return: The names of the settings that must be present and non-empty.
+    """
+    fields = REQUIRED_FIELDS.get(db_config.get('type'), ())
+
+    if db_config.get('type') == 'mysql':
+        if db_config.get('iam_auth'):
+            return tuple(field for field in fields if field != 'user')
+        return fields + ('password',)
+
+    return fields
+
+
+def db_user_from_token(token: str) -> str | None:
+    """
+    Read the database user out of an AWS RDS IAM token.
+
+    The token is a presigned URL and carries the user it was issued for as its `DBUser`
+    parameter, so the user does not have to be repeated in the configuration file.
+
+    :param token: The token returned by `rx rds password`.
+    :return: The database user, or None if the token does not name one.
+    """
+    _, _, query = (token or '').partition('?')
+    users = parse_qs(query).get('DBUser') or []
+    return users[0] or None if users else None
+
+
 def _strip_ansi(text_value: str | None) -> str:
     """
     Remove ANSI colour and cursor codes from CLI output.
@@ -80,11 +115,7 @@ def _validate_db_config(db_name: str, db_config: dict[str, Any]) -> dict[str, An
     """
     unresolved = db_config.pop('_unresolved_env', {})
 
-    required = REQUIRED_FIELDS.get(db_config.get('type'), ())
-    if db_config.get('type') == 'mysql' and not db_config.get('iam_auth'):
-        required = required + ('password',)
-
-    for key in required:
+    for key in required_fields(db_config):
         if db_config.get(key):
             continue
         if key in unresolved:
@@ -270,11 +301,30 @@ def mysql_connect(db_name: str) -> Connection:
         # 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']))
+
+        # The token names the user it was issued for, so `user` is optional in the config.
+        token_user = db_user_from_token(token)
+        user = db_config.get('user') or token_user
+        if not user:
+            raise ConfigError(
+                f"Database '{db_name}' has no 'user', and the token from 'rx rds password' "
+                f"did not name one either. Add a 'user' to {CONFIG_FILENAME}."
+            )
+        if token_user and db_config.get('user') and db_config['user'] != token_user:
+            # The token is signed for one user, so connecting as another is rejected by RDS
+            # with a bare access-denied. Say what is actually wrong instead.
+            raise ConfigError(
+                f"Database '{db_name}' is configured for user "
+                f"{db_config['user']!r}, but 'rx rds password' issued a token for "
+                f"{token_user!r}. Remove 'user' from {CONFIG_FILENAME} to use the token's "
+                "own user, or correct it to match."
+            )
+
         # 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"mysql+pymysql://{quote_plus(user)}:{quote_plus(token)}"
             f"@{host}:{port}/{database}"
         )
         # A CA bundle gets the certificate verified too; without one we still insist on

fullscript_spellbook-3.0.2/spellbook_config.yaml

@@ -0,0 +1,55 @@
+databases:
+  # Snowflake connection, with values written straight into this file.
+  # Spellbook warns about hardcoded credentials, so prefer the next example.
+  - name: snowflake_example
+    type: snowflake
+    account: your_account
+    user: snowflake_user_name
+    password: snowflake_password # Optional when a private key is given
+    private_key: snowflake_pk # Base64-encoded; used in preference to the password
+    private_key_passphrase: snowflake_pk_phrase # Optional, omit if the key has none
+    role: snowflake_role
+    warehouse: snowflake_warehouse
+    database: snowflake_database
+    schema: snowflake_schema # Optional, defaults to 'public'
+
+  # The same connection, reading its sensitive values from environment variables.
+  - name: snowflake_env_example
+    type: snowflake
+    account: ${SNOWFLAKE_ACCOUNT}
+    user: ${SNOWFLAKE_USER}
+    password: ${SNOWFLAKE_PASSWORD}
+    private_key: ${SNOW_PK}
+    private_key_passphrase: ${SNOW_PK_PASSPHRASE} # Optional
+    role: snowflake_role
+    warehouse: snowflake_warehouse
+    database: snowflake_database
+    schema: snowflake_schema
+
+  # MySQL connection using a stored password.
+  - name: mysql_example
+    type: mysql
+    host: your_host
+    port: 3306 # Optional, defaults to 3306
+    user: mysql_user_name
+    password: ${MYSQL_PASSWORD}
+    database: mysql_database
+
+  # MySQL connection using AWS RDS IAM authentication, so no password is stored.
+  # Spellbook fetches a temporary token on every connection, because they expire
+  # after about 15 minutes. Requires the `rx` CLI, which is Fullscript internal tooling.
+  - name: mysql_iam_example
+    type: mysql
+    host: ${MYSQL_HOST} # e.g. your-instance.abc123.us-east-1.rds.amazonaws.com
+    port: 3306
+    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
+    service_account: "your_base64_encoded_service_account_credentials_here"  # Add your Base64-encoded service account JSON here
+  # Google Sheets Service Account 2
+  - name: google_sheets_service_account_2
+    service_account: "your_base64_encoded_service_account_credentials_here"

{fullscript_spellbook-3.0.1 → fullscript_spellbook-3.0.2}/tests/test_db_magic.py

@@ -211,6 +211,94 @@ def test_iam_auth_fetches_a_fresh_token_per_connection(monkeypatch, config, engi
     assert 'token-two' in engines[1][0]
 
 
+# --- The IAM token names its own user ----------------------------------------------------
+# An RDS IAM token is a presigned URL carrying DBUser, so `user` need not be configured.
+
+@pytest.mark.parametrize('token, expected', [
+    (FAKE_TOKEN, 'iam_user'),
+    ('host:3306/?Action=connect&DBUser=first.last&X-Amz-Signature=x', 'first.last'),
+    ('host:3306/?DBUser=needs%40escaping', 'needs@escaping'),
+    ('host:3306/?Action=connect&X-Amz-Signature=x', None),   # no DBUser at all
+    ('host:3306/?DBUser=', None),                             # present but empty
+    ('not-a-url-at-all', None),
+    ('', None),
+])
+def test_db_user_is_read_from_the_token(token, expected):
+    assert db_magic.db_user_from_token(token) == expected
+
+
+def test_user_is_derived_from_the_token_when_not_configured(monkeypatch, config, engines):
+    without_user = {key: value for key, value in IAM_DB.items() if key != 'user'}
+    config(without_user)
+    monkeypatch.setattr(subprocess, 'run', fake_rx(stdout=FAKE_TOKEN))
+
+    db_magic.mysql_connect('reporting_db')
+
+    # FAKE_TOKEN carries DBUser=iam_user
+    assert engines[0][0].startswith('mysql+pymysql://iam_user:')
+
+
+def test_a_configured_user_is_still_honoured(monkeypatch, config, engines):
+    config(IAM_DB)
+    monkeypatch.setattr(subprocess, 'run', fake_rx(stdout=FAKE_TOKEN))
+
+    db_magic.mysql_connect('reporting_db')
+
+    assert engines[0][0].startswith('mysql+pymysql://iam_user:')
+
+
+def test_a_user_that_disagrees_with_the_token_is_reported_clearly(
+    monkeypatch, config, engines,
+):
+    """RDS rejects a mismatch with a bare access-denied, so catch it with a real message."""
+    config({**IAM_DB, 'user': 'someone.else'})
+    monkeypatch.setattr(subprocess, 'run', fake_rx(stdout=FAKE_TOKEN))
+
+    with pytest.raises(ConfigError) as error:
+        db_magic.mysql_connect('reporting_db')
+
+    message = str(error.value)
+    assert 'someone.else' in message
+    assert 'iam_user' in message
+    assert engines == [], 'no connection should be attempted'
+
+
+def test_a_token_without_a_user_and_no_config_user_raises(monkeypatch, config, engines):
+    without_user = {key: value for key, value in IAM_DB.items() if key != 'user'}
+    config(without_user)
+    monkeypatch.setattr(subprocess, 'run', fake_rx(
+        stdout='host:3306/?Action=connect&X-Amz-Signature=x',
+    ))
+
+    with pytest.raises(ConfigError, match="did not name one either"):
+        db_magic.mysql_connect('reporting_db')
+
+
+def test_user_is_not_required_in_config_for_iam_databases(config_file):
+    config_file({'name': 'db', 'type': 'mysql', 'host': 'h',
+                 'database': 'd', 'iam_auth': True})
+
+    assert db_magic.get_db_config('db').get('user') is None
+
+
+def test_user_is_still_required_for_password_databases(config_file):
+    config_file({'name': 'db', 'type': 'mysql', 'host': 'h',
+                 'database': 'd', 'password': 'p'})
+
+    with pytest.raises(ConfigError, match="required 'user'"):
+        db_magic.get_db_config('db')
+
+
+@pytest.mark.parametrize('db_config, expected', [
+    ({'type': 'mysql', 'iam_auth': True}, ('host', 'database')),
+    ({'type': 'mysql'}, ('host', 'user', 'database', 'password')),
+    ({'type': 'snowflake'}, ('account', 'user', 'role', 'warehouse', 'database')),
+    ({'type': 'postgres'}, ()),
+])
+def test_required_fields_per_database_type(db_config, expected):
+    assert db_magic.required_fields(db_config) == expected
+
+
 # --- 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:`,

fullscript_spellbook-3.0.1/spellbook_config.yaml

@@ -1,54 +0,0 @@
-databases:
-  # Snowflake Database Connection
-  - name: alias_of_your_connection
-    type: snowflake
-    account: your_account
-    user: snowflake_user_name # Optional for private key auth
-    password: snowflake_password # Optional, used if private key is not present
-    private_key: snowflake_pk # Base64-encoded private key
-    private_key_passphrase: snowflake_pk_phrase # Optional
-    role: snowflake_role
-    warehouse: snowflake_warehouse
-    database: snowflake_database
-    schema: snowflake_schema
-
-  - name: alias_of_your_connection_2
-    type: snowflake
-    account: ${SNOWFLAKE_ACCOUNT}
-    user: ${SNOWFLAKE_USER} # Example of using environment variables
-    password: ${SNOWFLAKE_PASSWORD} # Example of using environment variables
-    private_key: snowflake_pk  # Example of using environment variables
-    private_key_passphrase: snowflake_pk_phrase # Optional
-    role: snowflake_role
-    warehouse: snowflake_warehouse
-    database: snowflake_database
-    schema: snowflake_schema
-
-  # MySQL Database Connection
-  - name: alias_of_your_connection
-    type: mysql
-    host: your_host
-    port: 3306
-    user: mysql_user_name
-    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
-    service_account: "your_base64_encoded_service_account_credentials_here"  # Add your Base64-encoded service account JSON here
-  # Google Sheets Service Account 2
-  - name: google_sheets_service_account_2
-    service_account: "your_base64_encoded_service_account_credentials_here"
-