textprompts 0.0.1__tar.gz → 0.0.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: textprompts
-Version: 0.0.1
+Version: 0.0.2
 Summary: Minimal text-based prompt-loader with TOML front-matter
 Keywords: prompts,toml,frontmatter,template
 Author: Jan Siml
@@ -76,7 +76,7 @@ import textprompts
 prompt = textprompts.load_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 +86,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 +111,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 +193,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 +211,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
@@ -253,7 +256,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(
@@ -338,7 +341,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 +388,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 +463,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.2}/README.md

@@ -52,7 +52,7 @@ import textprompts
 prompt = textprompts.load_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 +62,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 +87,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 +169,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 +187,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
@@ -229,7 +232,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(
@@ -314,7 +317,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 +364,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 +439,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.2}/pyproject.toml

@@ -1,9 +1,10 @@
 [project]
 name = "textprompts"
-version = "0.0.1"
+version = "0.0.2"
 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"},
 ]

{textprompts-0.0.1 → textprompts-0.0.2}/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.2/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.2}/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,21 @@ 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(
+            path=path, meta=ignore_meta, prompt=PromptString(textwrap.dedent(raw))
+        )
 
     # For STRICT and ALLOW modes, try to parse front matter
     try:
@@ -72,7 +85,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 +127,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 +142,11 @@ 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(path=path, meta=meta, prompt=PromptString(textwrap.dedent(body)))

{textprompts-0.0.1 → textprompts-0.0.2}/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.2}/src/textprompts/config.py

@@ -30,6 +30,7 @@ class MetadataMode(Enum):
 
 # Global configuration variable
 _METADATA_MODE: MetadataMode = MetadataMode.IGNORE
+_WARN_ON_IGNORED_META: bool = True
 
 
 def set_metadata(mode: Union[MetadataMode, str]) -> None:
@@ -82,6 +83,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.2}/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.2/src/textprompts/models.py

@@ -0,0 +1,67 @@
+from datetime import date
+from pathlib import Path
+from typing import Any, Union
+
+from pydantic import BaseModel, Field, field_validator
+
+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
+
+    @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.2}/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.2/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.2/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.2}/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(),
-        )