Metadata-Version: 2.4
Name: dworshak-prompt
Version: 0.3.7
Summary: Multiplexed user input via console, GUI, and web, depending on availability.
Author-email: George Clayton Bennett <george.bennett@memphistn.gov>
Maintainer-email: George Clayton Bennett <george.bennett@memphistn.gov>
License-Expression: MIT
Project-URL: Homepage, https://github.com/city-of-memphis-wastewater/dworshak-prompt
Project-URL: Repository, https://github.com/city-of-memphis-wastewater/dworshak-prompt
Keywords: prompt,user-input,interactive,ci,cd,ci-cd,headless,non-interactive,cli,shell,bash,scripting,configuration,config-management,secrets,secret-management,credentials,environment-variables,dotenv,devops,automation,pipelines,github-actions,fallback,cross-platform,wsl
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dworshak-config>=0.2.7
Requires-Dist: dworshak-env>=0.1.7
Requires-Dist: dworshak-secret>=1.3.2
Requires-Dist: pyhabitat>=1.2.7
Provides-Extra: typer
Requires-Dist: typer>=0.21.1; extra == "typer"
Requires-Dist: rich>=14.3.2; extra == "typer"
Requires-Dist: typer-helptree>=0.2.8; extra == "typer"
Provides-Extra: crypto
Requires-Dist: cryptography>=46.0.3; extra == "crypto"
Requires-Dist: dworshak-secret[crypto]; extra == "crypto"
Provides-Extra: full
Requires-Dist: dworshak-prompt[crypto,typer]; extra == "full"
Dynamic: license-file

# dworshak-prompt

A Python utility that ensures you can always get user input by falling back through multiple interfaces.
`dworshak-prompt` is a CI-safe, shell-friendly prompting engine that integrates with persistent config and secret storage.

## How it works

It captures input by cycling through modes based on environment availability:

1. **Console** (CLI)
2. **GUI** (Tkinter)
3. **Web** (Local Browser Server)

Automatically skips incompatible modes (e.g., GUI on WSL) via `pyhabitat`.

### Install

Install on most systems.
```bash
pip install "dworshak-prompt[typer,cryptography]"
```

Install on Termux.
```bash
pkg add python-cryptography
uv venv --system-site-packages
uv add "dworshak-prompt[typer]"
```

### Obtain vs DworshakPrompt 

Use `Obtain` for managed config/secret storage; use `DworshakPrompt` directly if you want to handle values yourself.

## Usage

### Obtain
Leverage dworshak-config, dworshak-secret, and dworshak-env to automatically handle values.

```python
from dworshak_prompt import Obtain

obtain = Obtain()

obtain.config(service, item, message)
obtain.secret(service, item, message)
obtain.env(key, message)

```

### Ask

Prompt the user then handle values manually.

```python
from dworshak_prompt import DworshakPrompt, PromptMode

# Basic
val = DworshakPrompt().ask("Enter value")

# Options
val = DworshakPrompt().ask(
    message = "Secure Key",
    hide_input=True,
    interface_priority = [PromptMode.CLI, PromptMode.GUI]
    interface_avoid = {PromptMode.WEB}

)

```

Another example, for handling CI:

```python
from dworshak_prompt import Obtain

# If this runs in GitHub Actions, it returns "staging" immediately.
# If it runs on a laptop, it pops up a GUI or Console prompt.
obtain = Obtain()
val = obtain.env(
    key = "TARGET_ENV",
    message = "Target Environment",
    suggestion="production",  # What the human sees
    default="staging"         # What the CI/Headless system uses if the request fails.
)
```

Leveraging `dworshak-prompt` for calling and adding configured values.
The default config file path is "~/.dworshak/config.json".

```python
from dworshak_prompt import Obtain, PromptMode, InterruptBehavior, 

# Identify custom path for a specific project, and set defaults during instantiation of the Obtain class.
obtain = Obtain(
    config_path="~/.pipeline-eds/config.json"
    interface_priority = [PromptMode.GUI, PromptMode.WEB]
    interface_avoid = {PromptMode.CLI}
    interrupt_behavior = InterruptBehavior.EXIT,
    debug = True
    )
api_key = obtain.config("emerson-ovation-api","api_key", message="Enter EDS API Key")
```


Another example of the Obtain pattern.

```python
from O365 import Account
from dworshak_prompt import Obtain, InterruptBehavior, PromptMode
import os
import logging
logger=logging.getLogger(__name__)

avoid_set = set()
DWO_AVOID_CONSOLE = os.environ.get('DWO_AVOID_CONSOLE')
if  DWO_AVOID_CONSOLE == "1":
    avoid_set.add(PromptMode.CLI)
else:
    logger.warning("Use 'export DWO_AVOID_CONSOLE=1 to avoid the console, to make enable unhiding hidden input.'")
logger.debug(f"{avoid_set=}")
logger.debug(f"{DWO_AVOID_CONSOLE=}")

# Instantiate the prompt handler
prompt = Obtain(
    interrupt_behavior = InterruptBehavior.EXIT,
    interface_avoid = avoid_set
)

# Ask for client credentials securely
CLIENT_ID = prompt.secret(
    service="o365",
    item="CLIENT_ID",
    message="Enter your O365 Client ID: "
    ).value
CLIENT_SECRET = prompt.secret(
    service="o365",
    item="CLIENT_SECRET",
    message="Enter your O365 Client Secret: "
    ).value

# Prepare credentials tuple
credentials = (CLIENT_ID, CLIENT_SECRET)

# Initialize O365 account
account = Account(credentials)

# Authenticate (interactive for first-time login)
if not account.is_authenticated:
    account.authenticate(scopes=['https://graph.microsoft.com/Mail.Read'])

# Access mailbox and list folders
mailbox = account.mailbox()
folders = mailbox.list_folders()

print("Mailbox folders:")
for folder in folders:
    print("-", folder.name)
```


---

## CLI

The [dworshak](https://github.com/City-of-Memphis-Wastewater/dworshak) layer is the intended primary CLI entry point, but the `dworshak-prompt` CLI can be used directly.

```bash
pipx install "dworshak-prompt[typer]"
dworshak-prompt --version
dworshak-prompt --help
dworshak-prompt ask --message "Please state name" --interface web
```

`dworshak-prompt` is designed to be useful even without Python code. 
It can be used directly from shell scripts, CI pipelines, and ops tooling to safely obtain, persist, and reuse configuration values.

Piping and environment variable capture works, but will naturally fallback to GUI or Web input because in these cases `stdout` is not a TTY. However, you may continue to use console input and leverage `dev/tty` by using envionrmental variable `DWORSHAK_FORCE_INTERACTIVE_TTY`.

```zsh
# Enable console input during wrapped or piped shell capture.
export DWORSHAK_FORCE_INTERACTIVE_TTY=1
VAR=$(dworshak-prompt obtain secret "special_api" "password" --emit)
```

See the `dworshak-prompt` Typer CLI structure.
```
dworshak-prompt helptree
```

<p align="center">
  <img src="https://raw.githubusercontent.com/City-of-Memphis-Wastewater/dworshak-prompt/main/assets/dworshak-prompt_v0.3.7_helptree.svg" width="100%" alt="Screenshot of the dworshak-prompt CLI helptree">
</p>

`helptree` is utility funtion for Typer CLIs, imported from the `typer-helptree` library.

- GitHub: https://github.com/City-of-Memphis-Wastewater/typer-helptree
- PyPI: https://pypi.org/project/typer-helptree/

---

## Add dworshak-prompt to Python project
When using `uv` for dependency management.
```
uv add dworshak-prompt --extra typer
```

Or, when using raw `pip` for dependency management.
```
pip install "dworshak-prompt[typer]"
``` 

Including the `typer` optional dependency group ensures that Typer and Rich are included as a dependencies. 
Without this, the CLI and console prompting functionality are still stable, due to Python standard library fallbacks. 

---

## More Information

- [User Stories](https://github.com/City-of-Memphis-Wastewater/dworshak-prompt/blob/main/docs/USERS.md)

---

## Sister Projects in the Dworshak Ecosystem

* **CLI/Orchestrator:** [dworshak](https://github.com/City-of-Memphis-Wastewater/dworshak)
* **Interactive UI:** [dworshak-prompt](https://github.com/City-of-Memphis-Wastewater/dworshak-prompt)
* **Secrets Storage:** [dworshak-secret](https://github.com/City-of-Memphis-Wastewater/dworshak-secret)
* **Plaintext Pathed Configs:** [dworshak-config](https://github.com/City-of-Memphis-Wastewater/dworshak-config)
* **Classic .env Injection:** [dworshak-env](https://github.com/City-of-Memphis-Wastewater/dworshak-env)

```bash
pipx install dworshak
pip install dworshak-secret
pip install dworshak-config
pip install dworshak-env
pip install dworshak-prompt

```
