# How to Use the Text Parameter Type in Hypster for String Configuration

> Discover how to use the text parameter type in Hypster for string configuration. Learn to define string values with hp.text, ensuring robust input validation for your Hypster projects.

- Repository: [Gilad Rubin/hypster](https://github.com/gilad-rubin/hypster)
- Tags: how-to-guide
- Published: 2026-03-02

---

**Use `hp.text(default, name="param_name")` to define string values in Hypster configurations, which validates inputs through the `TextValidator` and requires a mandatory `name` argument for self-documenting parameter paths.**

The **text parameter type** in Hypster provides a type-safe way to handle string configuration values in the gilad-rubin/hypster library. Unlike standard Python strings, `hp.text()` creates a `SingleValueSpec` that enforces validation rules and integrates with Hypster's nested configuration contexts.

## Understanding the Text Parameter Architecture

Hypster routes all parameter type calls through a dynamic attribute system. When you call `hp.text()`, the `Hypster.__getattr__` method in [`src/hypster/hp.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/hp.py) (lines 99-106) maps the string `"text"` to the private `_text` method.

The `_text` method (lines 87-97 in [`src/hypster/hp.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/hp.py)) constructs a `SingleValueSpec` instance using `TextValidator`. Unlike numeric validators, `TextValidator` disables strict mode because strings lack bounded ranges. The method then invokes `_execute_single` to register the specification in the current configuration context.

During instantiation, [`src/hypster/hp_calls.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/hp_calls.py) (lines 89-101) validates supplied values against the `TextValidator`, ensuring only string types are accepted.

## Basic Syntax and Usage

The `hp.text()` function requires two arguments: a default string value and a mandatory `name` parameter that becomes the key in the final configuration dictionary.

```python
from hypster import hp

# Define a text parameter with explicit naming

model_name = hp.text("gpt-4", name="model_name")
system_prompt = hp.text("You are a helpful assistant.", name="system_prompt")

print(model_name)      # → "gpt-4"

print(system_prompt)   # → "You are a helpful assistant."

```

The `name` argument enables **fully-qualified parameter paths**, which proves essential when nesting configurations or integrating with Hyperparameter Optimization (HPO) frameworks.

## Validation and Type Safety

According to the source code in [`src/hypster/hp_calls.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/hp_calls.py), the `TextValidator` performs runtime type checking to guarantee that configured values remain strings. This catches type mismatches early in the configuration lifecycle.

The validation logic distinguishes `text` from numeric types (`hp.int`, `hp.float`) by omitting range constraints. While numeric validators enforce minimum and maximum bounds, `TextValidator` only verifies the Python `str` type, accepting any string length or content.

## Common Usage Patterns

### Nesting Parameters in Function Contexts

Hypster tracks the call stack to scope parameter names within nested functions, preventing naming collisions across different configuration contexts.

```python
from hypster import hp

def generate_prompt():
    prefix = hp.text("Task:", name="prompt_prefix")
    suffix = hp.text("Complete the above.", name="prompt_suffix")
    return {"prefix": prefix, "suffix": suffix}

config = generate_prompt()
print(config)

# {'prompt_prefix': 'Task:', 'prompt_suffix': 'Complete the above.'}

```

### Handling Missing Name Errors

Omitting the `name` parameter triggers an informative `RuntimeError` with the full call path, simplifying debugging.

```python
from hypster import hp

# This raises RuntimeError: text parameter requires a `name`

model_name = hp.text("gpt-4")

```

### Combining with Multi-Text Parameters

Use `hp.text()` alongside `hp.multi_text()` for configurations requiring both single strings and string collections.

```python
from hypster import hp

# Single string value

api_endpoint = hp.text("https://api.openai.com", name="api_endpoint")

# List of string values

stop_sequences = hp.multi_text(["###", "END"], name="stop_sequences")

```

Both calls return plain Python values (`str` and `List[str]`) compatible with standard library functions and third-party APIs.

## Summary

- **`hp.text()`** creates a `SingleValueSpec` using `TextValidator` to enforce string typing
- The **`name` parameter** is mandatory and defines the configuration dictionary key (implemented in [`src/hypster/hp.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/hp.py))
- **Type validation** occurs in [`src/hypster/hp_calls.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/hp_calls.py), ensuring only string values are accepted
- **Nested contexts** support reusable parameter names through call-stack tracking
- The API follows the **uniform pattern** shared with `hp.int()`, `hp.float()`, and `hp.bool()`

## Frequently Asked Questions

### What happens if I pass a non-string default value to hp.text()?

The `TextValidator` in [`src/hypster/hp_calls.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/hp_calls.py) validates the default value immediately during the configuration definition phase. Supplying a non-string default raises a validation error before runtime execution, preventing type mismatches from propagating to downstream code.

### Why does hp.text() require a name parameter while standard Python variables don't?

The `name` parameter enables Hypster to construct fully-qualified parameter paths for nested configurations and HPO integration. According to the documentation in [`docs/in-depth/hp-call-types/text-and-multi-text.md`](https://github.com/gilad-rubin/hypster/blob/main/docs/in-depth/hp-call-types/text-and-multi-text.md), this requirement makes configurations self-documenting and allows the same parameter name to exist in different lexical scopes without collision.

### Can I use hp.text() for multiline strings or empty strings?

Yes. The `TextValidator` accepts any valid Python string, including empty strings `""`, multiline strings using triple quotes, and Unicode content. The validator only checks the type (string), not the content length or character constraints, unlike numeric parameters that enforce bounds.