ostruct-cli 0.8.8__py3-none-any.whl → 0.8.29__py3-none-any.whl

ostruct/cli/cli.py

@@ -18,6 +18,33 @@ from .errors import (
 )
 from .exit_codes import ExitCode
 from .registry_updates import get_update_notification
+from .utils import fix_surrogate_escapes
+
+
+def fix_argv_encoding() -> None:
+    """Fix UTF-8 encoding issues in sys.argv.
+
+    This function addresses the surrogate escape issue where Python's sys.argv
+    contains surrogate characters (e.g., a backslash followed by 'udce2')
+    when processing command line arguments with non-ASCII characters. This
+    commonly happens with filenames containing characters like en dash (–) or
+    other Unicode characters.
+
+    The fix detects arguments containing surrogate escapes and converts them
+    back to proper UTF-8 strings.
+    """
+    try:
+        fixed_argv = []
+        for arg in sys.argv:
+            fixed_argv.append(fix_surrogate_escapes(arg))
+
+        # Replace sys.argv with the fixed version
+        sys.argv = fixed_argv
+
+    except Exception:
+        # If anything goes wrong with the encoding fix, continue with original argv
+        # This ensures the CLI doesn't break even if the fix fails
+        pass
 
 
 def create_cli_group() -> click.Group:
@@ -108,6 +135,9 @@ def create_cli() -> click.Command:
 
 def main() -> None:
     """Main entry point for the CLI."""
+    # Fix UTF-8 encoding issues in command line arguments before processing
+    fix_argv_encoding()
+
     # Load environment variables from .env file
     load_dotenv()
 

ostruct/cli/errors.py

@@ -291,7 +291,22 @@ class TemplateValidationError(TaskTemplateError):
 class SystemPromptError(TaskTemplateError):
     """Raised when there are issues with system prompt loading or processing."""
 
-    pass
+    def __init__(
+        self,
+        message: str,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize system prompt error.
+
+        Args:
+            message: Error message
+            context: Additional error context
+        """
+        super().__init__(
+            message,
+            context=context,
+            exit_code=ExitCode.VALIDATION_ERROR,
+        )
 
 
 class SchemaError(CLIError):

ostruct/cli/file_info.py

@@ -156,23 +156,45 @@ class FileInfo:
         Returns a path relative to the security manager's base directory.
         This ensures consistent path handling across the entire codebase.
 
+        For paths outside the base directory but within allowed directories,
+        returns the absolute path.
+
         Example:
             security_manager = SecurityManager(base_dir="/base")
             file_info = FileInfo("/base/file.txt", security_manager)
             print(file_info.path)  # Outputs: "file.txt"
 
+            # With allowed directory outside base:
+            file_info = FileInfo("/tmp/file.txt", security_manager)
+            print(file_info.path)  # Outputs: "/tmp/file.txt"
+
         Returns:
-            str: Path relative to security manager's base directory
+            str: Path relative to security manager's base directory, or absolute path
+                 if outside base directory but within allowed directories
 
         Raises:
-            ValueError: If the path is not within the base directory
+            ValueError: If the path is not within the base directory or allowed directories
         """
+        abs_path = Path(self.abs_path)
+        base_dir = Path(self.__security_manager.base_dir)
+
         try:
-            abs_path = Path(self.abs_path)
-            base_dir = Path(self.__security_manager.base_dir)
             return str(abs_path.relative_to(base_dir))
-        except ValueError as e:
-            logger.error("Error making path relative: %s", e)
+        except ValueError:
+            # Path is outside base_dir, check if it's in allowed directories
+            if self.__security_manager.is_path_allowed(abs_path):
+                logger.debug(
+                    "Path outside base_dir but allowed, returning absolute path: %s",
+                    abs_path,
+                )
+                return str(abs_path)
+
+            # Should never reach here if SecurityManager validation was done properly
+            logger.error(
+                "Error making path relative: %s is not within base directory %s",
+                abs_path,
+                base_dir,
+            )
             raise ValueError(
                 f"Path {abs_path} must be within base directory {base_dir}"
             )

ostruct/cli/file_list.py

@@ -320,6 +320,45 @@ class FileInfoList(List[FileInfo]):
             # Single file from file mapping
             return self[0].name
 
+    @property
+    def extension(self) -> str:
+        """Get the file extension of a single file without dot.
+
+        Returns:
+            str: Extension of the single file from file mapping.
+
+        Raises:
+            ValueError: If the list is empty or contains multiple files.
+        """
+        with self._lock:
+            if not self:
+                var_name = self._var_alias or "file_list"
+                raise ValueError(
+                    f"No files in '{var_name}'. Cannot access .extension property."
+                )
+
+            # Check for multiple files or directory mapping
+            if len(self) > 1:
+                var_name = self._var_alias or "file_list"
+                raise ValueError(
+                    f"'{var_name}' contains {len(self)} files. "
+                    f"Use '{{{{ {var_name}[0].extension }}}}' for the first file, "
+                    f"'{{{{ {var_name}|single.extension }}}}' if expecting exactly one file, "
+                    f"or loop over files with '{{%% for file in {var_name} %%}}{{{{ file.extension }}}}{{%% endfor %%}}'."
+                )
+
+            if self._from_dir:
+                var_name = self._var_alias or "file_list"
+                raise ValueError(
+                    f"'{var_name}' contains files from directory mapping. "
+                    f"Use '{{{{ {var_name}[0].extension }}}}' for the first file, "
+                    f"'{{{{ {var_name}|single.extension }}}}' if expecting exactly one file, "
+                    f"or loop over files with '{{%% for file in {var_name} %%}}{{{{ file.extension }}}}{{%% endfor %%}}'."
+                )
+
+            # Single file from file mapping
+            return self[0].extension
+
     @property
     def names(self) -> List[str]:
         """Get all filenames as a list."""

ostruct/cli/utils.py

@@ -5,6 +5,36 @@ from typing import Tuple
 from .errors import VariableNameError, VariableValueError
 
 
+def fix_surrogate_escapes(text: str) -> str:
+    """Fix UTF-8 encoding issues caused by surrogate escapes.
+
+    This function addresses the issue where Python's sys.argv contains
+    surrogate characters (e.g., a backslash followed by 'udce2') when
+    processing command line arguments with non-ASCII characters. This
+    commonly happens with filenames containing characters like en dash (–)
+    or other Unicode characters.
+
+    Args:
+        text: String that may contain surrogate escape characters
+
+    Returns:
+        String with surrogate escapes converted back to proper UTF-8
+    """
+    try:
+        # Check if the text contains surrogate characters
+        if any(0xDC00 <= ord(c) <= 0xDFFF for c in text):
+            # Convert surrogate escapes back to bytes, then decode as UTF-8
+            # This handles the case where Python used surrogateescape error handling
+            byte_data = text.encode("utf-8", "surrogateescape")
+            return byte_data.decode("utf-8")
+        else:
+            # No surrogate characters, return as-is
+            return text
+    except (UnicodeError, UnicodeDecodeError, UnicodeEncodeError):
+        # If conversion fails, return the original text
+        return text
+
+
 def parse_mapping(mapping: str) -> Tuple[str, str]:
     """Parse a mapping string in the format 'name=value'.
 

ostruct/cli/validators.py

@@ -26,6 +26,7 @@ from .template_processor import (
 )
 from .template_utils import validate_json_schema
 from .types import CLIParams
+from .utils import fix_surrogate_escapes
 
 logger = logging.getLogger(__name__)
 
@@ -145,6 +146,9 @@ def validate_variable(
 
     result = []
     for var in value:
+        # Fix any surrogate escape issues in the variable string
+        var = fix_surrogate_escapes(var)
+
         if "=" not in var:
             raise click.BadParameter(
                 f"Variable must be in format name=value: {var}"
@@ -152,6 +156,11 @@ def validate_variable(
         name, val = var.split("=", 1)
         name = name.strip()
         val = val.strip()
+
+        # Fix surrogate escapes in both name and value
+        name = fix_surrogate_escapes(name)
+        val = fix_surrogate_escapes(val)
+
         if not name.isidentifier():
             raise click.BadParameter(f"Invalid variable name: {name}")
         result.append((name, val))
@@ -179,6 +188,9 @@ def validate_json_variable(
 
     result = []
     for var in value:
+        # Fix any surrogate escape issues in the variable string
+        var = fix_surrogate_escapes(var)
+
         if "=" not in var:
             raise InvalidJSONError(
                 f"JSON variable must be in format name='{'json':\"value\"}': {var}"
@@ -186,6 +198,11 @@ def validate_json_variable(
         name, json_str = var.split("=", 1)
         name = name.strip()
         json_str = json_str.strip()
+
+        # Fix surrogate escapes in both name and JSON string
+        name = fix_surrogate_escapes(name)
+        json_str = fix_surrogate_escapes(json_str)
+
         if not name.isidentifier():
             raise VariableNameError(f"Invalid variable name: {name}")
         try:

{ostruct_cli-0.8.8.dist-info → ostruct_cli-0.8.29.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ostruct-cli
-Version: 0.8.8
+Version: 0.8.29
 Summary: CLI for OpenAI Structured Output with Multi-Tool Integration
 Author: Yaniv Golan
 Author-email: yaniv@golan.name
@@ -27,7 +27,7 @@ Requires-Dist: ijson (>=3.2.3,<4.0)
 Requires-Dist: jinja2 (>=3.1.2,<4.0)
 Requires-Dist: jsonschema (>=4.23.0,<5.0)
 Requires-Dist: mypy (>=1.0,<2.0) ; extra == "dev"
-Requires-Dist: myst-parser (>=2.0.0,<3.0) ; extra == "docs"
+Requires-Dist: myst-parser (>=3.0.0,<4.0) ; extra == "docs"
 Requires-Dist: openai (==1.81.0)
 Requires-Dist: openai-model-registry (>=0.7.0,<1.0)
 Requires-Dist: pre-commit (>=4.1.0,<5.0) ; extra == "dev"
@@ -42,9 +42,9 @@ Requires-Dist: pytest-rerunfailures (>=12.0,<13.0) ; extra == "dev"
 Requires-Dist: python-dotenv (>=1.0.1,<2.0)
 Requires-Dist: python-dotenv (>=1.0.1,<2.0) ; extra == "dev"
 Requires-Dist: pyyaml (>=6.0.2,<7.0)
-Requires-Dist: sphinx (>=7.0,<8.0) ; extra == "dev"
-Requires-Dist: sphinx (>=7.0,<8.0) ; extra == "docs"
-Requires-Dist: sphinx-design (>=0.5.0,<1.0) ; extra == "docs"
+Requires-Dist: sphinx (>=7.0.0,<8.0) ; extra == "dev"
+Requires-Dist: sphinx (>=7.0.0,<8.0) ; extra == "docs"
+Requires-Dist: sphinx-design (>=0.4.1,<1.0) ; extra == "docs"
 Requires-Dist: sphinx-rtd-theme (>=1.0,<2.0) ; extra == "docs"
 Requires-Dist: tenacity (>=8.2.3,<9.0) ; extra == "examples"
 Requires-Dist: tiktoken (==0.9.0)
@@ -216,23 +216,84 @@ Break down words into their components, showing their origins, meanings, and hie
 
 ## Installation
 
-### Quick Install (macOS)
+We provide multiple installation methods to suit different user needs. Choose the one that's right for you.
 
-For macOS users, we provide a one-line installer that handles everything automatically:
+<details>
+<summary><strong>Recommended: pipx (Python Users)</strong></summary>
+
+For users who have Python installed, `pipx` is the recommended installation method. It installs `ostruct` in an isolated environment, preventing conflicts with other Python packages.
+
+1. **Install pipx**:
+
+    ```bash
+    python3 -m pip install --user pipx
+    python3 -m pipx ensurepath
+    ```
+
+    *(Restart your terminal after running `ensurepath` to update your `PATH`)*
+
+2. **Install ostruct-cli**:
+
+    ```bash
+    pipx install ostruct-cli
+    ```
+
+</details>
+
+<details>
+<summary><strong>macOS: Homebrew</strong></summary>
+
+If you're on macOS and use Homebrew, you can install `ostruct` with a single command:
+
+```bash
+brew install yaniv-golan/ostruct/ostruct-cli
+```
+
+</details>
+
+<details>
+<summary><strong>Standalone Binaries (No Python Required)</strong></summary>
+
+We provide pre-compiled .zip archives for macOS, Windows, and Linux that do not require Python to be installed.
+
+1. Go to the [**Latest Release**](https://github.com/yaniv-golan/ostruct/releases/latest) page.
+2. Download the `.zip` file for your operating system (e.g., `ostruct-macos-latest.zip`, `ostruct-windows-latest.zip`, `ostruct-ubuntu-latest.zip`).
+3. Extract the `.zip` file. This will create a folder (e.g., `ostruct-macos-amd64`).
+4. On macOS/Linux, make the executable inside the extracted folder runnable:
+
+    ```bash
+    chmod +x /path/to/ostruct-macos-amd64/ostruct
+    ```
+
+5. Run the executable from within the extracted folder, as it depends on bundled libraries in the same directory.
+
+</details>
+
+<details>
+<summary><strong>Docker</strong></summary>
+
+If you prefer to use Docker, you can run `ostruct` from our official container image available on the GitHub Container Registry.
 
 ```bash
-curl -sSL https://github.com/yaniv-golan/ostruct/releases/latest/download/install-macos.sh | bash
+docker run -it --rm \
+  -v "$(pwd)":/app \
+  -w /app \
+  ghcr.io/yaniv-golan/ostruct:latest \
+  run template.j2 schema.json -ft input.txt
 ```
 
-This script will:
+This command mounts the current directory into the container and runs `ostruct`.
 
-- Install Python 3.10+ if needed (via Homebrew or python.org)
-- Install Homebrew if needed
-- Install ostruct-cli via pip
-- Configure your shell PATH automatically
-- Verify the installation works
+</details>
+
+### Uninstallation
 
-After installation, restart your terminal and test with `ostruct --version`.
+To uninstall `ostruct`, use the method corresponding to how you installed it:
+
+- **pipx**: `pipx uninstall ostruct-cli`
+- **Homebrew**: `brew uninstall ostruct-cli`
+- **Binaries**: Simply delete the binary file.
+- **Docker**: No uninstallation is needed for the image itself, but you can remove it with `docker rmi ghcr.io/yaniv-golan/ostruct:latest`.
 
 ### Manual Installation
 
@@ -446,6 +507,8 @@ tools:
 
 🚀 **New to ostruct?** Follow our [step-by-step quickstart guide](https://ostruct.readthedocs.io/en/latest/user-guide/quickstart.html) featuring Juno the beagle for a hands-on introduction.
 
+📝 **Template Scripting:** Learn ostruct's templating capabilities with the [template scripting guide](https://ostruct.readthedocs.io/en/latest/user-guide/ostruct_template_scripting_guide.html) - no prior Jinja2 knowledge required!
+
 📖 **Full Documentation:** <https://ostruct.readthedocs.io/>
 
 ### Quick Start

{ostruct_cli-0.8.8.dist-info → ostruct_cli-0.8.29.dist-info}/RECORD

@@ -2,7 +2,7 @@ ostruct/__init__.py,sha256=X6zo6V7ZNMv731Wi388aTVQngD1410ExGwGx4J6lpyo,187
 ostruct/cli/__init__.py,sha256=e-DtWRviCr3fIAJH4cB4UAvles3-rqnhJaTOlBn9TKs,871
 ostruct/cli/base_errors.py,sha256=o-877bJJA8yJWISRPy0KyL6wDu1-_avddmQIfVePuFM,5989
 ostruct/cli/cache_manager.py,sha256=ej3KrRfkKKZ_lEp2JswjbJ5bW2ncsvna9NeJu81cqqs,5192
-ostruct/cli/cli.py,sha256=pzOzKMvWQMRS1I9w4raAUi-O7IN6OKViNTcOeJGEqhI,4196
+ostruct/cli/cli.py,sha256=QtWoNskOvus9gYvxjSxdhXRpbdwIYwA9Di1f93bkVpE,5266
 ostruct/cli/click_options.py,sha256=UWLBIkfVMXcIMXInJFWNYNO9Ieg8YrJEzRfkKungy48,31730
 ostruct/cli/code_interpreter.py,sha256=lnnyEvUh2pGObN9ENpr-X4p0C0oIWiyG1CFQWW4akBQ,16726
 ostruct/cli/commands/__init__.py,sha256=3NHz-WZ9XqrnWWMksoV2MpYpHnjA-EO9lsrBOYeHcjY,723
@@ -12,12 +12,12 @@ ostruct/cli/commands/run.py,sha256=Cm9Yuf0DLt5CqKfgAYubhQRcvLdK1vqIIuz_ynjfhQ4,6
 ostruct/cli/commands/update_registry.py,sha256=7DQrPlCJScPVgE2HbFAM7UMap-EdYu58AQWfpI-H7Gw,2483
 ostruct/cli/config.py,sha256=7tKI1gWLpTISn5OorGWIx66N1J7XW2aq30hPNISZzQ0,9958
 ostruct/cli/cost_estimation.py,sha256=08hyE-kM5QYzj7y-KB3lMD_RxCMoM_Ve3-IQlSpJAo4,4483
-ostruct/cli/errors.py,sha256=sVOM_ZKvrtnmT8_WR-DfX2crs6HmvmwrbNQlxm-5_Ew,24669
+ostruct/cli/errors.py,sha256=Akw-_pAuvy18PKrlYdkpF0sNBrc82M4rGKtDWuPQpQg,25065
 ostruct/cli/exit_codes.py,sha256=gdvB1dpu0LalEUZrofpk5K6aTQ24n5AfkAK5umludHU,365
 ostruct/cli/explicit_file_processor.py,sha256=B6yUPbyn6MVd81GcyMVpORFwyaHFFESLwFixp2B6M5w,19767
 ostruct/cli/field_utils.py,sha256=bcRi1qQ0Ac2UCfrKSQ677_yu-VzaShm_zN7QLf98qc0,1939
-ostruct/cli/file_info.py,sha256=s8AHPtyU3__2LRJCCIEPuODYM43is4Y2Q_VDhBOl3XU,17395
-ostruct/cli/file_list.py,sha256=alRAguq4tj1zH0_qlWaRoyHo1G1Xmxqu9Xd4QP-zYP0,20268
+ostruct/cli/file_info.py,sha256=B5mFX9AI9-H6yM2FhcdVtwibFS6NbZplXPW9vYjozOs,18336
+ostruct/cli/file_list.py,sha256=upaXaQVmuxwjdmXzTRlvttMZjnpv_B2JzvmhoWTvsUg,21978
 ostruct/cli/file_search.py,sha256=N12mkji2ttvItLVPyAWE3KEfhTv8hV5IXPrQME2UFdE,15313
 ostruct/cli/file_utils.py,sha256=JZprQ-1LHQzI3eBfeCIS6VmxTa2fGUZHygGC8gcwpJM,24367
 ostruct/cli/json_extract.py,sha256=ZleIxat8g-JnA9VVqWgJaKxN7QzL25itQ8aP0Gb5e4Q,2650
@@ -61,11 +61,11 @@ ostruct/cli/token_utils.py,sha256=r4KPEO3Sec18Q6mU0aClK6XGShvusgUggXEQgEPPlaA,13
 ostruct/cli/token_validation.py,sha256=gmyPJ7B2gC_jSx_1wKZq87DEoFulj23X1XnVpO_aRNA,9930
 ostruct/cli/types.py,sha256=6nARJ4MF5HIank0t6KGU-PPHC0VpFh3R8fNJZBXwgbA,2903
 ostruct/cli/unattended_operation.py,sha256=kI95SSVJC_taxORXQYrce_qLEnuKc6edwn9tMOye-qs,9383
-ostruct/cli/utils.py,sha256=uY7c0NaINHWfnl77FcPE3TmYUXv3RqEeUTjrCMDij9A,922
-ostruct/cli/validators.py,sha256=lbxAUUVS5TPJ7HdYZ5yB7gUjJqfcClZCuh0oktoq0E0,15291
+ostruct/cli/utils.py,sha256=DV8KAx46rl3GgXLydVhrP6A1xY7ofyir3hEKUslSfek,2149
+ostruct/cli/validators.py,sha256=VbafaT7QyKAqpnHbqpibE3xkuaZ74e6zQ7Ih3WbzyRI,15844
 ostruct/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ostruct_cli-0.8.8.dist-info/LICENSE,sha256=DmGAkaYzhrdzTB9Y2Rvfzd3mJiF9ZrTOhxN8t6wrfHA,1098
-ostruct_cli-0.8.8.dist-info/METADATA,sha256=IHYyaz_fnJAXqPA8HFqdJuX-b5BEdPlFBaRthMbIE80,25918
-ostruct_cli-0.8.8.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-ostruct_cli-0.8.8.dist-info/entry_points.txt,sha256=NFq9IuqHVTem0j9zKjV8C1si_zGcP1RL6Wbvt9fUDXw,48
-ostruct_cli-0.8.8.dist-info/RECORD,,
+ostruct_cli-0.8.29.dist-info/LICENSE,sha256=DmGAkaYzhrdzTB9Y2Rvfzd3mJiF9ZrTOhxN8t6wrfHA,1098
+ostruct_cli-0.8.29.dist-info/METADATA,sha256=t-6EX_pD42Nt54cN-XFCc9yQVbbF5NasLGUwnempZL0,28124
+ostruct_cli-0.8.29.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+ostruct_cli-0.8.29.dist-info/entry_points.txt,sha256=NFq9IuqHVTem0j9zKjV8C1si_zGcP1RL6Wbvt9fUDXw,48
+ostruct_cli-0.8.29.dist-info/RECORD,,