Add multiple selectable config profiles to get_interface

cottoncandy previously supported a single set of connection settings
(keys, endpoint, bucket) split across the [login]/[basic]/[gdrive]
config sections. This adds named profiles so users can switch between
accounts/endpoints/buckets at instantiation time:

    cci = cc.get_interface(profile='mylab')

- options.py: add get_profile()/list_profiles() that resolve a
  [profile:NAME] section over the base sections, with `inherits` for
  profile inheritance (multi-level, with cycle detection).
- __init__.py: get_interface()/get_browser() accept profile=; the
  credential/bucket/endpoint/backend arguments default to None and are
  filled from the resolved profile, so explicit arguments still win.
- defaults.cfg: document profiles and add an explicit default backend key.
- tests: unit tests for profile resolution, inheritance, error cases, and
  get_interface precedence (no network).
- README: document profiles and inheritance.

Fully backward compatible: omitting profile= reproduces the current
behavior and existing configuration files keep working unchanged.

https://claude.ai/code/session_01UEkty8EbGpn3mWcwtcSwdw

Author: claude

README.md

@@ -57,6 +57,41 @@ By default, cottoncandy sets object and bucket permissions to ``authenticated-re
 
 Advanced (for admins): One can customize the cottoncandy system install by cloning the repo and modifying `defaults.cfg`. For example, one can set the default encryption key across the system for all users (`key = SoMeEncypTionKey`). When a user first uses cottoncandy, this default value will be copied to their personal configuration file. Note however that the user can still overwrite that value.
 
+### Profiles
+
+If you work across multiple accounts, endpoints, or buckets, you can define named
+**profiles** in your configuration file and select one when creating an interface:
+
+```python
+>>> cci = cc.get_interface(profile='mylab')
+```
+
+Each profile is a `[profile:NAME]` section that may set any subset of
+`access_key`, `secret_key`, `endpoint_url`, `default_bucket`, `signature_version`,
+`force_bucket_creation`, `backend`, and (for `backend = gdrive`) `secrets` and
+`credentials`. Any setting a profile omits falls back to the base
+`[login]`/`[basic]`/`[gdrive]` sections (the default profile, used when no
+`profile` is given). Arguments passed directly to `get_interface` always take
+precedence over the profile.
+
+Profiles can **inherit** from one another with `inherits`; a child only needs to
+specify the keys it overrides:
+
+```ini
+[profile:mylab]
+access_key = LABACCESSKEY
+secret_key = LABSECRETKEY
+endpoint_url = https://s3.example.edu/
+default_bucket = lab-shared
+
+[profile:mylab-scratch]
+inherits = mylab
+default_bucket = lab-scratch
+```
+
+Use `cottoncandy.options.list_profiles()` to see the profiles defined in your
+configuration.
+
 
 ## Getting started
 Setup the connection (endpoint, access and secret keys can be specified in the configuration file instead):

cottoncandy/__init__.py

@@ -21,13 +21,14 @@
 force_bucket_creation = string2bool(force_bucket_creation)
 
 
-def get_interface(bucket_name=default_bucket,
-                  ACCESS_KEY=ACCESS_KEY,
-                  SECRET_KEY=SECRET_KEY,
-                  endpoint_url=ENDPOINT_URL,
-                  force_bucket_creation=force_bucket_creation,
+def get_interface(bucket_name=None,
+                  ACCESS_KEY=None,
+                  SECRET_KEY=None,
+                  endpoint_url=None,
+                  force_bucket_creation=None,
                   verbose=True,
-                  backend='s3',
+                  backend=None,
+                  profile=None,
                   **kwargs):
     """Return an interface to the cloud.
 
@@ -40,6 +41,13 @@ def get_interface(bucket_name=default_bucket,
         The URL for the S3 gateway
     backend : 's3'|'gdrive'
         What backend to hook on to
+    profile : str, optional
+        Name of a ``[profile:NAME]`` section in the configuration file from
+        which to read the connection settings (access/secret keys, endpoint,
+        bucket, signature version, backend, gdrive credentials). Any setting a
+        profile omits falls back to the base ``[login]``/``[basic]``/``[gdrive]``
+        sections. Explicitly-passed arguments always take precedence over the
+        profile. See ``cottoncandy.options.list_profiles``.
     kwargs :
         S3 only. kwargs passed to botocore. For example,
         >>> from botocore.client import Config
@@ -52,40 +60,60 @@ def get_interface(bucket_name=default_bucket,
     """
     from cottoncandy.interfaces import DefaultInterface
 
+    # Resolve the profile (falls back to the base config sections). Any
+    # argument left as ``None`` is filled in from the resolved settings, so
+    # explicitly-passed arguments always win over the profile/config.
+    settings = options.get_profile(profile)
+
+    if bucket_name is None:
+        bucket_name = settings['default_bucket']
+    if ACCESS_KEY is None:
+        ACCESS_KEY = settings['access_key']
+    if SECRET_KEY is None:
+        SECRET_KEY = settings['secret_key']
+    if endpoint_url is None:
+        endpoint_url = settings['endpoint_url']
+    if backend is None:
+        backend = settings['backend'] or 's3'
+    if force_bucket_creation is None:
+        force_bucket_creation = string2bool(settings['force_bucket_creation'])
+    signature_version = settings['signature_version']
+
     if backend == 's3':
         if ACCESS_KEY in [False, "False"] or SECRET_KEY in [False, "False"]:
             ACCESS_KEY, SECRET_KEY = get_keys()
     elif backend == 'gdrive':
-        ACCESS_KEY = os.path.join(options.userdir, options.config.get('gdrive', 'secrets'))
-        SECRET_KEY = os.path.join(options.userdir, options.config.get('gdrive', 'credentials'))
+        ACCESS_KEY = os.path.join(options.userdir, settings['secrets'])
+        SECRET_KEY = os.path.join(options.userdir, settings['credentials'])
     else:
         pass
 
     if 'config' in kwargs:
         # user provided config
         if not kwargs['config'].signature_version:
             # config does not specify signature
-            kwargs['config'].signature_version = DEFAULT_SIGNATURE_VERSION
-    elif DEFAULT_SIGNATURE_VERSION:
+            kwargs['config'].signature_version = signature_version
+    elif signature_version:
         # no config but default signature exists
         from botocore.client import Config
-        kwargs['config'] = Config(signature_version=DEFAULT_SIGNATURE_VERSION)
+        kwargs['config'] = Config(signature_version=signature_version)
 
     interface = DefaultInterface(bucket_name,
                                  ACCESS_KEY,
                                  SECRET_KEY,
                                  endpoint_url,
                                  force_bucket_creation,
                                  verbose=verbose,
-                                 backend = backend,
+                                 backend=backend,
                                  **kwargs)
     return interface
 
 
-def get_browser(bucket_name=default_bucket,
-                ACCESS_KEY=ACCESS_KEY,
-                SECRET_KEY=SECRET_KEY,
-                endpoint_url=ENDPOINT_URL):
+def get_browser(bucket_name=None,
+                ACCESS_KEY=None,
+                SECRET_KEY=None,
+                endpoint_url=None,
+                profile=None):
     """Browser object that allows you to tab-complete your
     way through your objects
 
@@ -96,6 +124,10 @@ def get_browser(bucket_name=default_bucket,
     SECRET_KEY : str
     endpoint_url : str
         The URL for the S3 gateway
+    profile : str, optional
+        Name of a ``[profile:NAME]`` section in the configuration file from
+        which to read the connection settings. Explicitly-passed arguments take
+        precedence over the profile. See ``cottoncandy.options.list_profiles``.
 
     Returns
     -------
@@ -118,7 +150,19 @@ def get_browser(bucket_name=default_bucket,
     from cottoncandy.browser import S3Directory
     from cottoncandy.interfaces import DefaultInterface
 
-    if (ACCESS_KEY is False) and (SECRET_KEY is False):
+    # Resolve the profile (falls back to the base config sections); explicitly
+    # passed arguments win over the profile.
+    settings = options.get_profile(profile)
+    if bucket_name is None:
+        bucket_name = settings['default_bucket']
+    if ACCESS_KEY is None:
+        ACCESS_KEY = settings['access_key']
+    if SECRET_KEY is None:
+        SECRET_KEY = settings['secret_key']
+    if endpoint_url is None:
+        endpoint_url = settings['endpoint_url']
+
+    if ACCESS_KEY in [False, "False"] and SECRET_KEY in [False, "False"]:
         from .utils import get_keys
         ACCESS_KEY, SECRET_KEY = get_keys()
 

cottoncandy/defaults.cfg

@@ -13,6 +13,8 @@ force_bucket_creation = False
 path_separator = /
 signature_version =
 threads = 4
+# default backend: 's3', 'gdrive', or 'local'
+backend = s3
 
 [upload_settings]
 # in MB, except max_mpu_size_TB, and max_mpu_parts
@@ -43,3 +45,29 @@ do_compression = True
 small_array = gzip
 # >= 2 GB arrays
 large_array = Zstd
+
+# Profiles (optional)
+# -------------------
+# Define named profiles to switch between accounts/endpoints/buckets:
+#
+#     cci = cottoncandy.get_interface(profile='mylab')
+#
+# A profile section is named [profile:NAME] and may set any subset of:
+#     access_key, secret_key, endpoint_url, default_bucket,
+#     signature_version, force_bucket_creation, backend,
+#     secrets, credentials   (the last two are for backend = gdrive)
+# Anything a profile omits falls back to the [login]/[basic]/[gdrive] sections
+# above (the default profile).
+#
+# A profile can inherit from another profile with `inherits`; a child only needs
+# to specify the keys it overrides:
+#
+# [profile:mylab]
+# access_key = LABACCESSKEY
+# secret_key = LABSECRETKEY
+# endpoint_url = https://s3.example.edu/
+# default_bucket = lab-shared
+#
+# [profile:mylab-scratch]
+# inherits = mylab
+# default_bucket = lab-scratch

cottoncandy/options.py

@@ -84,3 +84,103 @@ def get_config():
     if needs_update:
         with open(usercfg, 'w') as configfile:
             config.write(configfile)
+
+
+# Profiles
+# --------
+# A profile bundles the connection-identity settings so users can switch
+# between accounts/endpoints/buckets via ``get_interface(profile='NAME')``.
+# Each profile lives in its own ``[profile:NAME]`` section and may set any
+# subset of the keys below. Anything a profile omits falls back to the base
+# ``[login]``/``[basic]``/``[gdrive]`` sections (the default profile). A profile
+# can inherit from another with ``inherits = PARENT`` and only specify the keys
+# it overrides.
+PROFILE_PREFIX = 'profile:'
+INHERITS_KEY = 'inherits'
+
+# logical name -> (base section, key) used as the default-profile fallback
+PROFILE_KEYS = {
+    'access_key': ('login', 'access_key'),
+    'secret_key': ('login', 'secret_key'),
+    'endpoint_url': ('login', 'endpoint_url'),
+    'default_bucket': ('basic', 'default_bucket'),
+    'signature_version': ('basic', 'signature_version'),
+    'force_bucket_creation': ('basic', 'force_bucket_creation'),
+    'backend': ('basic', 'backend'),
+    'secrets': ('gdrive', 'secrets'),
+    'credentials': ('gdrive', 'credentials'),
+}
+
+
+def list_profiles(cfg=None):
+    '''List the names of the profiles defined in the configuration.
+
+    Parameters
+    ----------
+    cfg : configparser.ConfigParser, optional
+        Defaults to the global cottoncandy config.
+
+    Returns
+    -------
+    profiles : list of str
+    '''
+    cfg = config if cfg is None else cfg
+    return [section[len(PROFILE_PREFIX):] for section in cfg.sections()
+            if section.startswith(PROFILE_PREFIX)]
+
+
+def _profile_chain(name, cfg, _seen=None):
+    '''Return the inheritance chain for a profile, root parent first.
+
+    Raises
+    ------
+    ValueError
+        If the profile (or a parent) does not exist, or if the ``inherits``
+        relationships form a cycle.
+    '''
+    _seen = [] if _seen is None else _seen
+    section = PROFILE_PREFIX + name
+    if not cfg.has_section(section):
+        raise ValueError('Unknown cottoncandy profile %r. Available: %s'
+                         % (name, list_profiles(cfg)))
+    if name in _seen:
+        raise ValueError('Circular profile inheritance: %s'
+                         % ' -> '.join(_seen + [name]))
+    _seen = _seen + [name]
+    if cfg.has_option(section, INHERITS_KEY):
+        parent = cfg.get(section, INHERITS_KEY).strip()
+        if parent:
+            return _profile_chain(parent, cfg, _seen) + [name]
+    return [name]
+
+
+def get_profile(name=None, cfg=None):
+    '''Resolve a profile into a dict of connection settings.
+
+    Values are resolved most-specific-last: the base ``[login]``/``[basic]``/
+    ``[gdrive]`` sections provide the defaults, then each profile in the
+    inheritance chain (root parent first) overlays the keys it sets.
+
+    Parameters
+    ----------
+    name : str or None
+        Profile name. ``None`` returns the base/default settings.
+    cfg : configparser.ConfigParser, optional
+        Defaults to the global cottoncandy config.
+
+    Returns
+    -------
+    settings : dict
+        Keys are those of ``PROFILE_KEYS``; missing values are ``None``.
+    '''
+    cfg = config if cfg is None else cfg
+    settings = {key: (cfg.get(section, option)
+                      if cfg.has_option(section, option) else None)
+                for key, (section, option) in PROFILE_KEYS.items()}
+    if name:
+        for profile_name in _profile_chain(name, cfg):
+            section = PROFILE_PREFIX + profile_name
+            for key in PROFILE_KEYS:
+                if cfg.has_option(section, key):
+                    settings[key] = cfg.get(section, key)
+    return settings