Getting Started

This guide will help you get started with TextPrompts in just a few minutes.

Installation

pip install textprompts

Or with uv:

uv add textprompts

Your First Prompt

  1. Create a simple prompt file hello.txt with TOML front-matter (default):
---
title = "Hello World"
description = "A simple greeting prompt"
---
Hello {name}! Welcome to TextPrompts.

YAML front-matter is also supported. The format is auto-detected:

---
title: "Hello World"
description: "A simple greeting prompt"
---
Hello {name}! Welcome to TextPrompts.
  1. Load and use it in Python:
from textprompts import load_prompt

# Load the prompt
prompt = load_prompt("hello.txt")

# Access metadata
print(prompt.meta.title)  # "Hello World"

# Use the prompt
message = prompt.prompt.format(name="Alice")
print(message)  # "Hello Alice! Welcome to TextPrompts."

Loading Multiple Prompts

Safe String Formatting

TextPrompts includes a PromptString class that prevents common formatting errors:

from textprompts import PromptString

template = PromptString("Hello {name}, you are {age} years old")

# ✅ This works
result = template.format(name="Alice", age=30)

# ❌ This raises ValueError: Missing format variables: ['age']
result = template.format(name="Alice")

Error Handling

TextPrompts provides detailed error messages:

from textprompts import load_prompt, TextPromptsError

try:
    prompt = load_prompt("nonexistent.txt")
except TextPromptsError as e:
    print(f"Failed to load prompt: {e}")

Common Patterns

Environment-specific prompts

import os
from textprompts import load_prompt

env = os.getenv("ENV", "development")
prompt = load_prompt(f"prompts/{env}/system.txt")

Cached loading

from functools import lru_cache
from textprompts import load_prompt

@lru_cache(maxsize=None)
def get_prompt(name):
    return load_prompt(f"prompts/{name}.txt")

Next Steps