Obtain: Smart Retrieval with Interactive Fallback

dworshak-prompt.Obtain is a unified mechanism to retrieve configuration, secrets, or environment values. Its purpose is to make workflows reliable, consistent, and CI-safe while reducing repetitive manual input.

---

How Obtain Works

1. Check existing storage first

2. Secrets → dworshak-secret vault

3. Configurations → dworshak-config JSON files

4. Environment variables → .env files via dworshak-env

5. Prompt only if needed

If the requested value is missing or overwrite=True, Obtain will ask the user for input.

Input is collected using a priority-aware default interface sequence.

1. Automatic persistence

Unless forget=True, any new or updated value is saved back to the original storage (vault, config, or env file).

Automatic Fallback (Default Behavior)

If no interface is specified, dworshak-prompt will try:

Console → GUI → Web

Unavailable interfaces are skipped automatically.

---

Using Obtain in Python

from dworshak_prompt import Obtain

# Initialize the manager
obtain = Obtain()

# Retrieve a secret (check vault first, prompt if missing)
secret_val = obtain.secret("my_service", "api_key").value

# Retrieve a config value (check file first, prompt if missing)
config_val = obtain.config("my_service", "timeout", suggestion="30").value

# Retrieve an environment value (check .env first, prompt if missing)
env_val = obtain.env("DATABASE_URL").value

Using Obtain with Interface Control

from dworshak_prompt import obtain, PromptMode

result = obtain.secret(
    "github",
    "token",
    message="Enter your GitHub API token",
    interface_priority=[PromptMode.GUI,PromptMode.CONSOLE],
    interface_avoid={PromptMode.WEB}
)

if result:
    print(result.status_message)
    token = result.value
else:
    print("User cancelled.")

Interface Selection

The prompting interface can be controlled with PromptMode.

Mode	Behavior
PromptMode.CONSOLE	Force terminal input
PromptMode.GUI	Use a Tkinter dialog
PromptMode.WEB	Launch a local browser prompt
None	Automatic fallback

Example forcing a GUI dialog:

from dworshak_prompt import obtain, PromptMode

result = obtain.config(
    "web_service",
    "timeout",
    suggestion="30",
    interface_priority=[PromptMode.GUI]
)

Avoiding an Interface

You can also skip specific interfaces:

result = obtain.env(
    "DATABASE_URL",
    interface_avoid={PromptMode.WEB}
)

This will try:

Console → GUI

but never the web interface.

---

Arguments in the Obtain Functions

These arguments are used in Obtain().config(), Obtain().env(), and Obtain().secret() functions.

• service: str
• item: str
• message: str | None = None
• suggestion: str | None = None
• default: str | None = None
• interface_priority: list[PromptMode] | None = None
• interface_avoid: set[PromptMode] | None = None
• path: str | Path | None = None
• overwrite: bool = False
• forget: bool = False

---

Data Structures

Under the hood, ObtainResult data structures are returned by the functions in the Obtain class. The functions in question are: config(), env(), and secret().

Class	Purpose
ObtainResult	Generic wrapper for a retrieved value
SecretData	Overrides status_message for secrets
ConfigData	Alias for ObtainResult for config values
EnvData	Alias for ObtainResult for environment variables

ObtainResult contains:

• value: Optional[str] — the retrieved value

• is_new: Optional[bool] — True if stored just now, False if already known, None if user cancelled

• status_message: str — human-readable status

---

CLI Usage

Beyond Python scripting, the obtain pattern can be deveraged in the console for managing individual secrets and configuration values. There is hygenic separation between stderr and stdout for console printing, such that values can be piped or captured and leveraged for bash scripting, etc.

VAL=(dworshak prompt obtain secret "aws" "password" --emit)

By default, when a prompt is wrapped, it will see the process as non-interactive and fallback to using Web or GUI input. A developer can choose to use console input via /dev/tty if they set the DWORSHAK_FORCE_INTERACTIVE_TTY to 1.

export DWORSHAK_FORCE_INTERACTIVE_TTY=1

---

Key Features

• Storage-aware first: never prompts unnecessarily

• Fallback interfaces: console → GUI → web

• CI-safe: non-interactive environments return defaults

• Persistent by default: stores new values automatically

• Flexible: supports secrets, config files, and environment variables