xplain.config

Configuration and credential management module for secure authentication.

create_session

xplain.config.create_session(profile=None, url=None, user=None, password=None, config_path=None, jwt_dispatch_url=None, jwt_cookie_name=None, jwt_token=None, **kwargs)

Create Xsession with credentials from multiple sources.

Supports named profiles for managing multiple environments:

Credential sources (in priority order): 1. Direct parameters (url, user, password, jwt_*) 2. Profile-specific environment variables (XPLAIN_<PROFILE>_URL, etc.) 3. Profile from config file (~/.xplainpyrc) 4. Default environment variables (XPLAIN_URL, XPLAIN_USER, XPLAIN_PASSWORD) 5. Default profile from config file

Parameters

profile (Optional[str]) – Profile name (e.g., ‘staging’, ‘production’)
url (Optional[str]) – Server URL (overrides profile)
user (Optional[str]) – Username (overrides profile)
password (Optional[str]) – Password (overrides profile)
config_path (Optional[pathlib.Path]) – Path to config file (default: ~/.xplainpyrc)
jwt_dispatch_url (Optional[str]) – JWT dispatch URL (overrides profile)
jwt_cookie_name (Optional[str]) – JWT cookie name (overrides profile)
jwt_token (Optional[str]) – JWT token (overrides profile)
**kwargs – Additional parameters passed to Xsession()

Returns

Configured Xsession instance

Raises

ValueError – If password is not provided from any source

Return type

Xsession

Examples

>>> # Use default profile or env vars
>>> session = create_session()

>>> # Use specific profile
>>> session = create_session(profile='staging')

>>> # Override profile settings
>>> session = create_session(profile='prod', user='admin')

>>> # Override JWT token for refresh
>>> session = create_session(profile='prod-jwt', jwt_token=get_fresh_token())

>>> # List available profiles
>>> from xplain.config import list_profiles
>>> print(list_profiles())

Example:

from xplain import create_session

# Use default profile or environment variables
session = create_session()

# Use specific profile
session = create_session(profile='staging')

# Override settings
session = create_session(profile='prod', jwt_token=get_fresh_token())

get_credentials

xplain.config.get_credentials(url=None, user=None, password=None, profile=None, config_path=None, jwt_dispatch_url=None, jwt_cookie_name=None, jwt_token=None)

Get Xplain credentials from multiple sources with priority order: 1. Direct parameters (highest priority) 2. Profile-specific environment variables (XPLAIN_<PROFILE>_*, XPLAIN_<PROFILE>_JWT_*) 3. Profile from config file 4. Default environment variables (XPLAIN_*, XPLAIN_JWT_*) 5. Default profile from config file 6. Defaults (url only)

Supports both password-based and JWT-based authentication.

Parameters

url (Optional[str]) – Server URL
user (Optional[str]) – Username
password (Optional[str]) – Password (for password-based auth)
profile (Optional[str]) – Profile name (e.g., ‘staging’, ‘production’)
config_path (Optional[pathlib.Path]) – Path to config file (default: ~/.xplainpyrc)
jwt_dispatch_url (Optional[str]) – JWT dispatch URL (for JWT auth)
jwt_cookie_name (Optional[str]) – JWT cookie name (for JWT auth)
jwt_token (Optional[str]) – JWT token value (for JWT auth)

Returns

Dictionary with authentication parameters (password or JWT fields)

Return type

Dict[str, Any]

Example

>>> # Password-based
>>> creds = get_credentials(profile='staging')
>>> session = Xsession(**creds)

>>> # JWT-based
>>> creds = get_credentials(profile='jwt-prod')
>>> session = Xsession(**creds)

Example:

from xplain import get_credentials, Xsession

creds = get_credentials(profile='staging')
session = Xsession(**creds)

load_profile

xplain.config.load_profile(profile_name=None, config_path=None)

Load a specific profile from config file.

Supports both multi-profile and single-credential config formats. Profiles can use either password-based or JWT-based authentication.

Multi-profile format:

{
  "profiles": {
    "local": {
      "url": "...",
      "user": "...",
      "password": "..."
    },
    "staging": {
      "url": "...",
      "user": "...",
      "jwt_dispatch_url": "...",
      "jwt_cookie_name": "...",
      "jwt_token": "..."
    }
  },
  "default": "local"
}

Single-credential format (legacy):

{"url": "...", "user": "...", "password": "..."}

Parameters

profile_name (Optional[str]) – Name of profile to load (default: use ‘default’ from config)
config_path (Optional[pathlib.Path]) – Path to config file (default: ~/.xplainpyrc)

Returns

Dictionary with authentication parameters (password-based or JWT-based)

Raises

ValueError – If profile not found

Return type

Dict[str, Any]

Example

>>> # Password-based profile
>>> creds = load_profile('staging')
>>> session = Xsession(**creds)

>>> # JWT-based profile
>>> creds = load_profile('jwt-prod')
>>> session = Xsession(**creds)

Example:

from xplain import load_profile

creds = load_profile('production')
print(f"Using {creds['url']}")

list_profiles

xplain.config.list_profiles(config_path=None)

List available profiles from config file.

Parameters: config_path (Optional[pathlib.Path]) – Path to config file (default: ~/.xplainpyrc)
Returns: List of profile names
Return type: list

Example

>>> profiles = list_profiles()
>>> print(f"Available: {', '.join(profiles)}")

Example:

from xplain import list_profiles

profiles = list_profiles()
print(f"Available: {', '.join(profiles)}")

load_config_file

xplain.config.load_config_file(config_path=None)

Load Xplain configuration from a JSON file.

Parameters: config_path (Optional[pathlib.Path]) – Path to config file. Defaults to ~/.xplainpyrc
Returns: Dictionary with configuration (empty if file doesn’t exist)
Return type: Dict[str, Any]

Example ~/.xplainpyrc:

{
  "url": "http://localhost:8080",
  "user": "myuser",
  "password": "mypassword"
}

Example:

from xplain import load_config_file

config = load_config_file()
print(config.get('profiles', {}).keys())