textprompts 0.0.1__tar.gz → 0.0.3__tar.gz

{textprompts-0.0.1 → textprompts-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: textprompts
-Version: 0.0.1
+Version: 0.0.3
 Summary: Minimal text-based prompt-loader with TOML front-matter
 Keywords: prompts,toml,frontmatter,template
 Author: Jan Siml
@@ -24,6 +24,13 @@ Description-Content-Type: text/markdown
 
 # textprompts
 
+[![PyPI version](https://img.shields.io/pypi/v/textprompts.svg)](https://pypi.org/project/textprompts/)
+[![Python versions](https://img.shields.io/pypi/pyversions/textprompts.svg)](https://pypi.org/project/textprompts/)
+[![CI status](https://github.com/svilupp/textprompts/workflows/CI/badge.svg)](https://github.com/svilupp/textprompts/actions)
+[![Coverage](https://img.shields.io/codecov/c/github/svilupp/textprompts)](https://codecov.io/gh/svilupp/textprompts)
+[![License](https://img.shields.io/pypi/l/textprompts.svg)](https://github.com/svilupp/textprompts/blob/main/LICENSE)
+
+
 > **So simple, it's not even worth vibing about coding yet it just makes so much sense.**
 
 Are you tired of vendors trying to sell you fancy UIs for prompt management that just make your system more confusing and harder to debug? Isn't it nice to just have your prompts **next to your code**? 
@@ -59,7 +66,6 @@ title = "Customer Greeting"
 version = "1.0.0"
 description = "Friendly greeting for customer support"
 ---
-
 Hello {customer_name}!
 
 Welcome to {company_name}. We're here to help you with {issue_type}.
@@ -74,9 +80,11 @@ import textprompts
 
 # Just load it - works with or without metadata
 prompt = textprompts.load_prompt("greeting.txt")
+# Or simply
+alt = textprompts.Prompt("greeting.txt")
 
 # Use it safely - all placeholders must be provided
-message = prompt.body.format(
+message = prompt.prompt.format(
     customer_name="Alice",
     company_name="ACME Corp", 
     issue_type="billing question",
@@ -86,19 +94,22 @@ message = prompt.body.format(
 print(message)
 
 # Or use partial formatting when needed
-partial = prompt.body.format(
+partial = prompt.prompt.format(
     customer_name="Alice",
     company_name="ACME Corp",
     skip_validation=True
 )
 # Result: "Hello Alice!\n\nWelcome to ACME Corp. We're here to help you with {issue_type}.\n\nBest regards,\n{agent_name}"
+
+# Prompt objects expose `.meta` and `.prompt`.
+# Use `prompt.prompt.format()` for safe formatting or `str(prompt)` for raw text.
 ```
 
 **Even simpler** - no metadata required:
 ```python
 # simple_prompt.txt contains just: "Analyze this data: {data}"
 prompt = textprompts.load_prompt("simple_prompt.txt")  # Just works!
-result = prompt.body.format(data="sales figures")
+result = prompt.prompt.format(data="sales figures")
 ```
 
 ## Core Features
@@ -108,9 +119,9 @@ result = prompt.body.format(data="sales figures")
 Never ship a prompt with missing variables again:
 
 ```python
-from textprompts import SafeString
+from textprompts import PromptString
 
-template = SafeString("Hello {name}, your order {order_id} is {status}")
+template = PromptString("Hello {name}, your order {order_id} is {status}")
 
 # ✅ Strict formatting - all placeholders must be provided
 result = template.format(name="Alice", order_id="12345", status="shipped")
@@ -190,14 +201,14 @@ response = openai.chat.completions.create(
     messages=[
         {
             "role": "system",
-            "content": system_prompt.body.format(
+            "content": system_prompt.prompt.format(
                 company_name="ACME Corp",
                 support_level="premium"
             )
         },
         {
             "role": "user", 
-            "content": user_prompt.body.format(
+            "content": user_prompt.prompt.format(
                 query="How do I return an item?",
                 customer_tier="premium"
             )
@@ -208,7 +219,7 @@ response = openai.chat.completions.create(
 
 ### Function Calling (Tool Definitions)
 
-Yes, you can version control your function schemas too:
+Yes, you can version control your whole tool schemas too:
 
 ```python
 # tools/search_products.txt
@@ -217,7 +228,6 @@ title = "Product Search Tool"
 version = "2.1.0"
 description = "Search our product catalog"
 ---
-
 {
     "type": "function",
     "function": {
@@ -253,7 +263,7 @@ from textprompts import load_prompt
 
 # Load and parse the tool definition
 tool_prompt = load_prompt("tools/search_products.txt")
-tool_schema = json.loads(tool_prompt.body)
+tool_schema = json.loads(tool_prompt.prompt)
 
 # Use with OpenAI
 response = openai.chat.completions.create(
@@ -303,7 +313,6 @@ description = "What this prompt does"
 created = "2024-01-15"
 tags = ["customer-support", "greeting"]
 ---
-
 Your prompt content goes here.
 
 Use {variables} for templating.
@@ -317,6 +326,10 @@ Choose the right level of strictness for your use case:
 2. **ALLOW** - Load metadata if present, don't worry about completeness  
 3. **STRICT** - Require complete metadata (title, description, version) for production safety
 
+You can also set the environment variable `TEXTPROMPTS_METADATA_MODE` to one of
+`strict`, `allow`, or `ignore` before importing the library to configure the
+default mode.
+
 ```python
 # Set globally
 textprompts.set_metadata("ignore")   # Default: simple file loading
@@ -338,7 +351,7 @@ Load a single prompt file.
 
 Returns a `Prompt` object with:
 - `prompt.meta`: Metadata from TOML front-matter (always present)
-- `prompt.body`: The prompt content as a `SafeString`
+- `prompt.prompt`: The prompt content as a `PromptString`
 - `prompt.path`: Path to the original file
 
 ### `load_prompts(*paths, recursive=False, glob="*.txt", meta=None, max_files=1000)`
@@ -385,14 +398,14 @@ save_prompt("my_prompt.txt", "You are a helpful assistant.")
 save_prompt("my_prompt.txt", prompt_object)
 ```
 
-### `SafeString`
+### `PromptString`
 
 A string subclass that validates `format()` calls:
 
 ```python
-from textprompts import SafeString
+from textprompts import PromptString
 
-template = SafeString("Hello {name}, you are {role}")
+template = PromptString("Hello {name}, you are {role}")
 
 # Strict formatting (default) - all placeholders required
 result = template.format(name="Alice", role="admin")  # ✅ Works
@@ -460,8 +473,8 @@ textprompts validate prompts/
 4. **Test your prompts**: Write unit tests for critical prompts
    ```python
    def test_greeting_prompt():
-       prompt = load_prompt("greeting.txt")
-       result = prompt.body.format(customer_name="Test")
+    prompt = load_prompt("greeting.txt")
+    result = prompt.prompt.format(customer_name="Test")
        assert "Test" in result
    ```
 

{textprompts-0.0.1 → textprompts-0.0.3}/README.md

@@ -1,5 +1,12 @@
 # textprompts
 
+[![PyPI version](https://img.shields.io/pypi/v/textprompts.svg)](https://pypi.org/project/textprompts/)
+[![Python versions](https://img.shields.io/pypi/pyversions/textprompts.svg)](https://pypi.org/project/textprompts/)
+[![CI status](https://github.com/svilupp/textprompts/workflows/CI/badge.svg)](https://github.com/svilupp/textprompts/actions)
+[![Coverage](https://img.shields.io/codecov/c/github/svilupp/textprompts)](https://codecov.io/gh/svilupp/textprompts)
+[![License](https://img.shields.io/pypi/l/textprompts.svg)](https://github.com/svilupp/textprompts/blob/main/LICENSE)
+
+
 > **So simple, it's not even worth vibing about coding yet it just makes so much sense.**
 
 Are you tired of vendors trying to sell you fancy UIs for prompt management that just make your system more confusing and harder to debug? Isn't it nice to just have your prompts **next to your code**? 
@@ -35,7 +42,6 @@ title = "Customer Greeting"
 version = "1.0.0"
 description = "Friendly greeting for customer support"
 ---
-
 Hello {customer_name}!
 
 Welcome to {company_name}. We're here to help you with {issue_type}.
@@ -50,9 +56,11 @@ import textprompts
 
 # Just load it - works with or without metadata
 prompt = textprompts.load_prompt("greeting.txt")
+# Or simply
+alt = textprompts.Prompt("greeting.txt")
 
 # Use it safely - all placeholders must be provided
-message = prompt.body.format(
+message = prompt.prompt.format(
     customer_name="Alice",
     company_name="ACME Corp", 
     issue_type="billing question",
@@ -62,19 +70,22 @@ message = prompt.body.format(
 print(message)
 
 # Or use partial formatting when needed
-partial = prompt.body.format(
+partial = prompt.prompt.format(
     customer_name="Alice",
     company_name="ACME Corp",
     skip_validation=True
 )
 # Result: "Hello Alice!\n\nWelcome to ACME Corp. We're here to help you with {issue_type}.\n\nBest regards,\n{agent_name}"
+
+# Prompt objects expose `.meta` and `.prompt`.
+# Use `prompt.prompt.format()` for safe formatting or `str(prompt)` for raw text.
 ```
 
 **Even simpler** - no metadata required:
 ```python
 # simple_prompt.txt contains just: "Analyze this data: {data}"
 prompt = textprompts.load_prompt("simple_prompt.txt")  # Just works!
-result = prompt.body.format(data="sales figures")
+result = prompt.prompt.format(data="sales figures")
 ```
 
 ## Core Features
@@ -84,9 +95,9 @@ result = prompt.body.format(data="sales figures")
 Never ship a prompt with missing variables again:
 
 ```python
-from textprompts import SafeString
+from textprompts import PromptString
 
-template = SafeString("Hello {name}, your order {order_id} is {status}")
+template = PromptString("Hello {name}, your order {order_id} is {status}")
 
 # ✅ Strict formatting - all placeholders must be provided
 result = template.format(name="Alice", order_id="12345", status="shipped")
@@ -166,14 +177,14 @@ response = openai.chat.completions.create(
     messages=[
         {
             "role": "system",
-            "content": system_prompt.body.format(
+            "content": system_prompt.prompt.format(
                 company_name="ACME Corp",
                 support_level="premium"
             )
         },
         {
             "role": "user", 
-            "content": user_prompt.body.format(
+            "content": user_prompt.prompt.format(
                 query="How do I return an item?",
                 customer_tier="premium"
             )
@@ -184,7 +195,7 @@ response = openai.chat.completions.create(
 
 ### Function Calling (Tool Definitions)
 
-Yes, you can version control your function schemas too:
+Yes, you can version control your whole tool schemas too:
 
 ```python
 # tools/search_products.txt
@@ -193,7 +204,6 @@ title = "Product Search Tool"
 version = "2.1.0"
 description = "Search our product catalog"
 ---
-
 {
     "type": "function",
     "function": {
@@ -229,7 +239,7 @@ from textprompts import load_prompt
 
 # Load and parse the tool definition
 tool_prompt = load_prompt("tools/search_products.txt")
-tool_schema = json.loads(tool_prompt.body)
+tool_schema = json.loads(tool_prompt.prompt)
 
 # Use with OpenAI
 response = openai.chat.completions.create(
@@ -279,7 +289,6 @@ description = "What this prompt does"
 created = "2024-01-15"
 tags = ["customer-support", "greeting"]
 ---
-
 Your prompt content goes here.
 
 Use {variables} for templating.
@@ -293,6 +302,10 @@ Choose the right level of strictness for your use case:
 2. **ALLOW** - Load metadata if present, don't worry about completeness  
 3. **STRICT** - Require complete metadata (title, description, version) for production safety
 
+You can also set the environment variable `TEXTPROMPTS_METADATA_MODE` to one of
+`strict`, `allow`, or `ignore` before importing the library to configure the
+default mode.
+
 ```python
 # Set globally
 textprompts.set_metadata("ignore")   # Default: simple file loading
@@ -314,7 +327,7 @@ Load a single prompt file.
 
 Returns a `Prompt` object with:
 - `prompt.meta`: Metadata from TOML front-matter (always present)
-- `prompt.body`: The prompt content as a `SafeString`
+- `prompt.prompt`: The prompt content as a `PromptString`
 - `prompt.path`: Path to the original file
 
 ### `load_prompts(*paths, recursive=False, glob="*.txt", meta=None, max_files=1000)`
@@ -361,14 +374,14 @@ save_prompt("my_prompt.txt", "You are a helpful assistant.")
 save_prompt("my_prompt.txt", prompt_object)
 ```
 
-### `SafeString`
+### `PromptString`
 
 A string subclass that validates `format()` calls:
 
 ```python
-from textprompts import SafeString
+from textprompts import PromptString
 
-template = SafeString("Hello {name}, you are {role}")
+template = PromptString("Hello {name}, you are {role}")
 
 # Strict formatting (default) - all placeholders required
 result = template.format(name="Alice", role="admin")  # ✅ Works
@@ -436,8 +449,8 @@ textprompts validate prompts/
 4. **Test your prompts**: Write unit tests for critical prompts
    ```python
    def test_greeting_prompt():
-       prompt = load_prompt("greeting.txt")
-       result = prompt.body.format(customer_name="Test")
+    prompt = load_prompt("greeting.txt")
+    result = prompt.prompt.format(customer_name="Test")
        assert "Test" in result
    ```
 

{textprompts-0.0.1 → textprompts-0.0.3}/pyproject.toml

@@ -1,9 +1,10 @@
 [project]
 name = "textprompts"
-version = "0.0.1"
+version = "0.0.3"
 description = "Minimal text-based prompt-loader with TOML front-matter"
 readme = "README.md"
 license = "MIT"
+license-file = "LICENSE"
 authors = [
     {name = "Jan Siml", email = "49557684+svilupp@users.noreply.github.com"},
 ]
@@ -37,6 +38,9 @@ dev = [
     "ruff>=0.12.2",
     "pre-commit>=3.0.0",
 ]
+test = [
+    "pydantic-ai>=0.4.5",
+]
 
 [build-system]
 requires = ["uv_build>=0.7.19,<0.8.0"]

{textprompts-0.0.1 → textprompts-0.0.3}/src/textprompts/__init__.py

@@ -1,4 +1,10 @@
-from .config import MetadataMode, get_metadata, set_metadata
+from .config import (
+    MetadataMode,
+    get_metadata,
+    set_metadata,
+    skip_metadata,
+    warn_on_ignored_metadata,
+)
 from .errors import (
     FileMissingError,
     InvalidMetadataError,
@@ -8,7 +14,7 @@ from .errors import (
 )
 from .loaders import load_prompt, load_prompts
 from .models import Prompt, PromptMeta
-from .safe_string import SafeString
+from .prompt_string import PromptString, SafeString
 from .savers import save_prompt
 
 __all__ = [
@@ -17,10 +23,13 @@ __all__ = [
     "save_prompt",
     "Prompt",
     "PromptMeta",
+    "PromptString",
     "SafeString",
     "MetadataMode",
     "set_metadata",
     "get_metadata",
+    "skip_metadata",
+    "warn_on_ignored_metadata",
     "TextPromptsError",
     "FileMissingError",
     "MissingMetadataError",

textprompts-0.0.3/src/textprompts/__main__.py

@@ -0,0 +1,8 @@
+"""Command-line entry point for ``python -m textprompts``."""  # pragma: no cover
+
+from textprompts.cli import main  # pragma: no cover
+
+__all__ = ["main"]  # pragma: no cover
+
+if __name__ == "__main__":  # pragma: no cover - small entrypoint wrapper
+    main()  # pragma: no cover

{textprompts-0.0.1 → textprompts-0.0.3}/src/textprompts/_parser.py

@@ -4,13 +4,13 @@ from typing import Optional
 
 try:
     import tomllib
-except ImportError:
+except ImportError:  # pragma: no cover - Python <3.11 fallback
     import tomli as tomllib  # type: ignore[import-not-found, no-redef]
 
-from .config import MetadataMode
+from .config import MetadataMode, warn_on_ignored_metadata
 from .errors import InvalidMetadataError, MalformedHeaderError, MissingMetadataError
 from .models import Prompt, PromptMeta
-from .safe_string import SafeString
+from .prompt_string import PromptString
 
 DELIM = "---"
 
@@ -59,8 +59,25 @@ def parse_file(path: Path, *, metadata_mode: MetadataMode) -> Prompt:
 
     # Handle IGNORE mode - treat entire file as body
     if metadata_mode == MetadataMode.IGNORE:
+        if (
+            warn_on_ignored_metadata()
+            and raw.startswith(DELIM)
+            and raw.find(DELIM, len(DELIM)) != -1
+        ):
+            import warnings
+
+            warnings.warn(
+                "Metadata detected but ignored; use set_metadata('allow') or skip_metadata(skip_warning=True) to silence",
+                stacklevel=2,
+            )
         ignore_meta = PromptMeta(title=path.stem)
-        return Prompt(path=path, meta=ignore_meta, body=SafeString(textwrap.dedent(raw)))
+        return Prompt.model_validate(
+            {
+                "path": path,
+                "meta": ignore_meta,
+                "prompt": PromptString(textwrap.dedent(raw)),
+            }
+        )
 
     # For STRICT and ALLOW modes, try to parse front matter
     try:
@@ -72,7 +89,7 @@ def parse_file(path: Path, *, metadata_mode: MetadataMode) -> Prompt:
                 f"{e}. If this file has no metadata and starts with '---', "
                 f"use meta=MetadataMode.IGNORE to skip metadata parsing."
             ) from e
-        raise
+        raise  # pragma: no cover - reraised to preserve stack
 
     meta: Optional[PromptMeta] = None
     if header_txt is not None:
@@ -114,7 +131,7 @@ def parse_file(path: Path, *, metadata_mode: MetadataMode) -> Prompt:
             ) from e
         except InvalidMetadataError:
             raise
-        except Exception as e:
+        except Exception as e:  # pragma: no cover - unlikely generic error
             raise InvalidMetadataError(f"Invalid metadata: {e}") from e
 
     else:
@@ -129,11 +146,17 @@ def parse_file(path: Path, *, metadata_mode: MetadataMode) -> Prompt:
         meta = PromptMeta()
 
     # Always ensure we have metadata with a title
-    if not meta:
+    if not meta:  # pragma: no cover - meta is never falsy but kept for safety
         meta = PromptMeta()
 
     # Use filename as title if not provided
     if meta.title is None:
         meta.title = path.stem
 
-    return Prompt(path=path, meta=meta, body=SafeString(textwrap.dedent(body)))
+    return Prompt.model_validate(
+        {
+            "path": path,
+            "meta": meta,
+            "prompt": PromptString(textwrap.dedent(body)),
+        }
+    )

{textprompts-0.0.1 → textprompts-0.0.3}/src/textprompts/cli.py

@@ -28,4 +28,4 @@ def main() -> None:
 
 
 if __name__ == "__main__":
-    main()
+    main()  # pragma: no cover - simple CLI entry point

{textprompts-0.0.1 → textprompts-0.0.3}/src/textprompts/config.py

@@ -2,6 +2,7 @@
 Global configuration for textprompts metadata handling.
 """
 
+import os
 from enum import Enum
 from typing import Union
 
@@ -29,7 +30,14 @@ class MetadataMode(Enum):
 
 
 # Global configuration variable
-_METADATA_MODE: MetadataMode = MetadataMode.IGNORE
+_env_mode = os.getenv("TEXTPROMPTS_METADATA_MODE")
+try:
+    _METADATA_MODE: MetadataMode = (
+        MetadataMode(_env_mode.lower()) if _env_mode else MetadataMode.IGNORE
+    )
+except ValueError:
+    _METADATA_MODE = MetadataMode.IGNORE
+_WARN_ON_IGNORED_META: bool = True
 
 
 def set_metadata(mode: Union[MetadataMode, str]) -> None:
@@ -82,6 +90,20 @@ def get_metadata() -> MetadataMode:
     return _METADATA_MODE
 
 
+def skip_metadata(*, skip_warning: bool = False) -> None:
+    """Convenience setter for ignoring metadata with optional warnings."""
+
+    global _WARN_ON_IGNORED_META
+    _WARN_ON_IGNORED_META = not skip_warning  # pragma: no cover
+    set_metadata(MetadataMode.IGNORE)  # pragma: no cover - simple wrapper
+
+
+def warn_on_ignored_metadata() -> bool:
+    """Return whether warnings for ignored metadata are enabled."""
+
+    return _WARN_ON_IGNORED_META
+
+
 def _resolve_metadata_mode(meta: Union[MetadataMode, str, None]) -> MetadataMode:
     """
     Resolve the metadata mode from parameters and global config.

{textprompts-0.0.1 → textprompts-0.0.3}/src/textprompts/loaders.py

@@ -96,17 +96,25 @@ def load_prompts(
         if pth.is_dir():
             itr: Iterable[Path] = pth.rglob(glob) if recursive else pth.glob(glob)
             for f in itr:
-                if max_files and file_count >= max_files:
+                if (
+                    max_files and file_count >= max_files
+                ):  # pragma: no cover - boundary check
                     from .errors import TextPromptsError
 
-                    raise TextPromptsError(f"Exceeded max_files limit of {max_files}")
+                    raise TextPromptsError(
+                        f"Exceeded max_files limit of {max_files}"
+                    )  # pragma: no cover - boundary check
                 collected.append(load_prompt(f, meta=meta))
                 file_count += 1
         else:
-            if max_files and file_count >= max_files:
+            if (
+                max_files and file_count >= max_files
+            ):  # pragma: no cover - boundary check
                 from .errors import TextPromptsError
 
-                raise TextPromptsError(f"Exceeded max_files limit of {max_files}")
+                raise TextPromptsError(
+                    f"Exceeded max_files limit of {max_files}"
+                )  # pragma: no cover - boundary check
             collected.append(load_prompt(pth, meta=meta))
             file_count += 1
 

textprompts-0.0.3/src/textprompts/models.py

@@ -0,0 +1,85 @@
+from datetime import date
+from pathlib import Path
+from typing import Any, Union
+
+from pydantic import BaseModel, Field, field_validator
+
+from .config import MetadataMode
+from .prompt_string import PromptString
+
+
+class PromptMeta(BaseModel):
+    title: Union[str, None] = Field(default=None, description="Human-readable name")
+    version: Union[str, None] = Field(default=None)
+    author: Union[str, None] = Field(default=None)
+    created: Union[date, None] = Field(default=None)
+    description: Union[str, None] = Field(default=None)
+
+
+class Prompt(BaseModel):
+    path: Path
+    meta: Union[PromptMeta, None]
+    prompt: PromptString
+
+    def __init__(
+        self,
+        path: Union[str, Path],
+        meta: Union[PromptMeta, MetadataMode, str, None] = None,
+        prompt: Union[str, PromptString, None] = None,
+    ) -> None:
+        """Initialize Prompt from fields or load from file."""
+        if prompt is None:
+            from .loaders import load_prompt
+
+            loaded = load_prompt(path, meta=meta)
+            super().__init__(**loaded.model_dump())
+        else:
+            if isinstance(prompt, str):
+                prompt = PromptString(prompt)
+            super().__init__(path=Path(path), meta=meta, prompt=prompt)
+
+    @field_validator("prompt")
+    @classmethod
+    def prompt_not_empty(cls, v: str) -> PromptString:
+        if not v.strip():
+            raise ValueError("Prompt body is empty")
+        return PromptString(v)
+
+    def __repr__(self) -> str:
+        if self.meta and self.meta.title:
+            if self.meta.version:
+                return (
+                    f"Prompt(title='{self.meta.title}', version='{self.meta.version}')"
+                    " # use .format() or str()"
+                )
+            return f"Prompt(title='{self.meta.title}') # use .format() or str()"
+        return f"Prompt(path='{self.path}') # use .format() or str()"
+
+    def __str__(self) -> str:
+        return str(self.prompt)
+
+    @property
+    def body(self) -> PromptString:
+        import warnings
+
+        warnings.warn(
+            "Prompt.body is deprecated; use .prompt instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.prompt
+
+    def __len__(self) -> int:
+        return len(self.prompt)
+
+    def __getitem__(self, item: int | slice) -> str:
+        return self.prompt[item]
+
+    def __add__(self, other: str) -> str:
+        return str(self.prompt) + str(other)
+
+    def strip(self, *args: Any, **kwargs: Any) -> str:
+        return self.prompt.strip(*args, **kwargs)
+
+    def format(self, *args: Any, **kwargs: Any) -> str:
+        return self.prompt.format(*args, **kwargs)

{textprompts-0.0.1 → textprompts-0.0.3}/src/textprompts/placeholder_utils.py

@@ -1,7 +1,7 @@
 """
 Utility functions for extracting and validating placeholders in format strings.
 
-This module provides robust placeholder extraction and validation for SafeString
+This module provides robust placeholder extraction and validation for PromptString
 formatting operations.
 """
 
@@ -53,7 +53,10 @@ def extract_placeholders(text: str) -> Set[str]:
 
 
 def validate_format_args(
-    placeholders: Set[str], args: Tuple[Any, ...], kwargs: Dict[str, Any], skip_validation: bool = False
+    placeholders: Set[str],
+    args: Tuple[Any, ...],
+    kwargs: Dict[str, Any],
+    skip_validation: bool = False,
 ) -> None:
     """
     Validate that format arguments match the placeholders in the template.

textprompts-0.0.3/src/textprompts/prompt_string.py

@@ -0,0 +1,60 @@
+from typing import Any, Set
+
+from pydantic import GetCoreSchemaHandler
+from pydantic_core import core_schema
+
+from .placeholder_utils import extract_placeholders, validate_format_args
+
+
+class PromptString(str):
+    """String subclass that validates ``format()`` calls."""
+
+    placeholders: Set[str]
+
+    def __new__(cls, value: str) -> "PromptString":
+        instance = str.__new__(cls, value)
+        instance.placeholders = extract_placeholders(value)
+        return instance
+
+    def format(self, *args: Any, **kwargs: Any) -> str:
+        """Format with validation and optional partial formatting."""
+        skip_validation = kwargs.pop("skip_validation", False)
+        source = str(self).strip()
+        if skip_validation:
+            return self._partial_format(*args, source=source, **kwargs)
+        validate_format_args(self.placeholders, args, kwargs, skip_validation=False)
+        return str.format(source, *args, **kwargs)
+
+    def _partial_format(
+        self, *args: Any, source: str | None = None, **kwargs: Any
+    ) -> str:
+        """Partial formatting - replace placeholders that have values."""
+        all_kwargs = kwargs.copy()
+        for i, arg in enumerate(args):
+            all_kwargs[str(i)] = arg
+
+        result = source if source is not None else str(self)
+        for placeholder in self.placeholders:
+            if placeholder in all_kwargs:
+                pattern = f"{{{placeholder}}}"
+                if pattern in result:
+                    try:
+                        result = result.replace(pattern, str(all_kwargs[placeholder]))
+                    except (KeyError, ValueError):  # pragma: no cover - defensive
+                        pass
+        return result
+
+    def __repr__(self) -> str:
+        return f"PromptString({str.__repr__(self)}, placeholders={self.placeholders})"
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, source_type: Any, handler: GetCoreSchemaHandler
+    ) -> core_schema.CoreSchema:
+        return core_schema.no_info_after_validator_function(
+            cls, core_schema.str_schema()
+        )
+
+
+# Backwards compatibility alias
+SafeString = PromptString

textprompts-0.0.3/src/textprompts/safe_string.py

@@ -0,0 +1,5 @@
+"""Backward-compatible alias module."""  # pragma: no cover
+
+from .prompt_string import PromptString, SafeString  # pragma: no cover
+
+__all__ = ["PromptString", "SafeString"]  # pragma: no cover

{textprompts-0.0.1 → textprompts-0.0.3}/src/textprompts/savers.py

@@ -25,7 +25,7 @@ def save_prompt(path: Union[str, Path], content: Union[str, Prompt]) -> None:
     >>> prompt = Prompt(
     ...     path=Path("my_prompt.txt"),
     ...     meta=PromptMeta(title="Assistant", version="1.0.0", description="A helpful AI"),
-    ...     body="You are a helpful assistant."
+    ...     prompt="You are a helpful assistant."
     ... )
     >>> save_prompt("my_prompt.txt", prompt)
     """
@@ -59,7 +59,7 @@ version = ""
 
         lines.append("---")
         lines.append("")
-        lines.append(str(content.body))
+        lines.append(str(content.prompt))
 
         path.write_text("\n".join(lines), encoding="utf-8")
     else:

textprompts-0.0.1/src/textprompts/models.py

@@ -1,42 +0,0 @@
-from datetime import date
-from pathlib import Path
-from typing import Union
-
-from pydantic import BaseModel, Field, field_validator
-
-from .safe_string import SafeString
-
-
-class PromptMeta(BaseModel):
-    title: Union[str, None] = Field(default=None, description="Human-readable name")
-    version: Union[str, None] = Field(default=None)
-    author: Union[str, None] = Field(default=None)
-    created: Union[date, None] = Field(default=None)
-    description: Union[str, None] = Field(default=None)
-
-
-class Prompt(BaseModel):
-    path: Path
-    meta: Union[PromptMeta, None]
-    body: SafeString
-
-    @field_validator("body")
-    @classmethod
-    def body_not_empty(cls, v: str) -> SafeString:
-        if not v.strip():
-            raise ValueError("Prompt body is empty")
-        return SafeString(v)
-
-    def __repr__(self) -> str:
-        if self.meta and self.meta.title:
-            if self.meta.version:
-                return (
-                    f"Prompt(title='{self.meta.title}', version='{self.meta.version}')"
-                )
-            else:
-                return f"Prompt(title='{self.meta.title}')"
-        else:
-            return f"Prompt(path='{self.path}')"
-
-    def __str__(self) -> str:
-        return str(self.body)

textprompts-0.0.1/src/textprompts/safe_string.py

@@ -1,110 +0,0 @@
-from typing import Any, Set
-
-from pydantic import GetCoreSchemaHandler
-from pydantic_core import core_schema
-
-from .placeholder_utils import extract_placeholders, validate_format_args
-
-
-class SafeString(str):
-    """
-    A string subclass that validates format() calls to ensure all placeholders are provided.
-
-    This prevents common errors where format variables are missing, making prompt templates
-    more reliable and easier to debug.
-
-    Attributes:
-        placeholders: Set of placeholder names found in the string
-    """
-
-    placeholders: Set[str]
-
-    def __new__(cls, value: str) -> "SafeString":
-        """Create a new SafeString instance with extracted placeholders."""
-        instance = str.__new__(cls, value)
-        instance.placeholders = extract_placeholders(value)
-        return instance
-
-    def format(self, *args: Any, **kwargs: Any) -> str:
-        """
-        Format the string with configurable validation behavior.
-
-        By default (skip_validation=False), this method validates that all placeholders
-        have corresponding values and raises ValueError if any are missing.
-
-        When skip_validation=True, it performs partial formatting, replacing only
-        the placeholders for which values are provided.
-
-        Args:
-            *args: Positional arguments for formatting
-            skip_validation: If True, perform partial formatting without validation
-            **kwargs: Keyword arguments for formatting
-
-        Returns:
-            The formatted string
-
-        Raises:
-            ValueError: If skip_validation=False and any placeholder is missing
-        """
-        skip_validation = kwargs.pop('skip_validation', False)
-        if skip_validation:
-            # Partial formatting - replace only available placeholders
-            return self._partial_format(*args, **kwargs)
-        else:
-            # Strict formatting - validate all placeholders are provided
-            validate_format_args(self.placeholders, args, kwargs, skip_validation=False)
-            return str.format(self, *args, **kwargs)
-
-    def _partial_format(self, *args: Any, **kwargs: Any) -> str:
-        """
-        Perform partial formatting, replacing only the placeholders that have values.
-
-        Args:
-            *args: Positional arguments for formatting
-            **kwargs: Keyword arguments for formatting
-
-        Returns:
-            The partially formatted string
-        """
-        # Convert positional args to keyword args
-        all_kwargs = kwargs.copy()
-        for i, arg in enumerate(args):
-            all_kwargs[str(i)] = arg
-
-        # Build a format string with only available placeholders
-        result = str(self)
-
-        # Replace placeholders one by one if they have values
-        for placeholder in self.placeholders:
-            if placeholder in all_kwargs:
-                # Create a single-placeholder format string
-                placeholder_pattern = f"{{{placeholder}}}"
-                if placeholder_pattern in result:
-                    try:
-                        # Replace this specific placeholder
-                        result = result.replace(
-                            placeholder_pattern, str(all_kwargs[placeholder])
-                        )
-                    except (KeyError, ValueError):
-                        # If replacement fails, leave the placeholder as is
-                        pass
-
-        return result
-
-    def __str__(self) -> str:
-        """Return the string representation."""
-        return str.__str__(self)
-
-    def __repr__(self) -> str:
-        """Return the string representation for debugging."""
-        return f"SafeString({str.__repr__(self)}, placeholders={self.placeholders})"
-
-    @classmethod
-    def __get_pydantic_core_schema__(
-        cls, source_type: Any, handler: GetCoreSchemaHandler
-    ) -> core_schema.CoreSchema:
-        """Support for Pydantic v2 schema generation."""
-        return core_schema.no_info_after_validator_function(
-            cls,
-            core_schema.str_schema(),
-        )