omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/handlers/models/model_filesystem_delete_result.py

@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Filesystem Delete File Result Model.
+
+This module provides the Pydantic model for the filesystem.delete_file operation
+result, replacing untyped dict[str, object] patterns.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class ModelDeleteFileResult(BaseModel):
+    """Result from filesystem.delete_file operation.
+
+    Contains metadata about the delete operation.
+
+    Attributes:
+        path: The resolved absolute path to the file (or where it would be).
+        deleted: True if the file was actually deleted by this operation.
+        was_missing: True if the file was already missing when the operation
+            was called (only relevant when missing_ok=True).
+
+    Example:
+        >>> result = ModelDeleteFileResult(
+        ...     path="/data/temp.txt",
+        ...     deleted=True,
+        ...     was_missing=False,
+        ... )
+        >>> print(result.deleted)
+        True
+
+        >>> missing_result = ModelDeleteFileResult(
+        ...     path="/data/nonexistent.txt",
+        ...     deleted=False,
+        ...     was_missing=True,
+        ... )
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    path: str = Field(
+        min_length=1,
+        description="Resolved absolute path to the file.",
+    )
+    deleted: bool = Field(
+        description="True if the file was deleted by this operation.",
+    )
+    was_missing: bool = Field(
+        description="True if the file was already missing.",
+    )
+
+    @model_validator(mode="after")
+    def _validate_flags(self) -> ModelDeleteFileResult:
+        """Validate that deleted and was_missing cannot both be True.
+
+        A file cannot have been deleted by this operation if it was already
+        missing when the operation was called.
+
+        Returns:
+            Self if validation passes.
+
+        Raises:
+            ValueError: If both deleted and was_missing are True.
+        """
+        if self.deleted and self.was_missing:
+            raise ValueError("deleted and was_missing cannot both be True")
+        return self
+
+
+__all__: list[str] = ["ModelDeleteFileResult"]

omnibase_infra/handlers/models/model_filesystem_directory_entry.py

@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Filesystem Directory Entry Model.
+
+This module provides the Pydantic model for a single directory entry,
+used in the filesystem.list_directory operation result.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelDirectoryEntry(BaseModel):
+    """Metadata for a single directory entry.
+
+    Represents a file or directory within a listed directory.
+
+    Attributes:
+        name: The name of the entry (filename or directory name).
+        path: The full path to the entry.
+        is_file: True if the entry is a regular file.
+        is_dir: True if the entry is a directory.
+        is_symlink: True if the entry is a symbolic link.
+        size: Size in bytes (0 for directories).
+        modified: Last modification time as Unix timestamp (seconds since epoch).
+
+    Example:
+        >>> entry = ModelDirectoryEntry(
+        ...     name="config.json",
+        ...     path="/data/config.json",
+        ...     is_file=True,
+        ...     is_dir=False,
+        ...     is_symlink=False,
+        ...     size=1024,
+        ...     modified=1704067200.0,
+        ... )
+        >>> print(entry.is_file)
+        True
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    name: str = Field(
+        min_length=1,
+        description="Name of the entry (filename or directory name).",
+    )
+    path: str = Field(
+        min_length=1,
+        description="Full path to the entry.",
+    )
+    is_file: bool = Field(
+        description="True if the entry is a regular file.",
+    )
+    is_dir: bool = Field(
+        description="True if the entry is a directory.",
+    )
+    is_symlink: bool = Field(
+        description="True if the entry is a symbolic link.",
+    )
+    size: int = Field(
+        ge=0,
+        description="Size in bytes (0 for directories).",
+    )
+    modified: float = Field(
+        description="Last modification time as Unix timestamp.",
+    )
+
+
+__all__: list[str] = ["ModelDirectoryEntry"]

omnibase_infra/handlers/models/model_filesystem_ensure_directory_payload.py

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Filesystem Ensure Directory Payload Model.
+
+This module provides the Pydantic model for the filesystem.ensure_directory operation
+payload, replacing untyped dict[str, object] patterns.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelEnsureDirectoryPayload(BaseModel):
+    """Payload for filesystem.ensure_directory operation.
+
+    Specifies the directory to create and options.
+
+    Attributes:
+        path: Absolute or relative path to the directory to ensure.
+            The path will be validated against the allowed_paths whitelist.
+            Parent directories will be created as needed (like mkdir -p).
+        exist_ok: If True (default), don't raise an error if the directory
+            already exists. If False, raise an error if it exists.
+
+    Example:
+        >>> payload = ModelEnsureDirectoryPayload(path="/data/output/reports")
+        >>> print(payload.exist_ok)
+        True
+
+        >>> strict_payload = ModelEnsureDirectoryPayload(
+        ...     path="/data/new_dir",
+        ...     exist_ok=False,
+        ... )
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    path: str = Field(
+        min_length=1,
+        description="Path to the directory to ensure. Validated against allowed_paths.",
+    )
+    exist_ok: bool = Field(
+        default=True,
+        description="If True, don't error if directory already exists.",
+    )
+
+
+__all__: list[str] = ["ModelEnsureDirectoryPayload"]

omnibase_infra/handlers/models/model_filesystem_ensure_directory_result.py

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Filesystem Ensure Directory Result Model.
+
+This module provides the Pydantic model for the filesystem.ensure_directory operation
+result, replacing untyped dict[str, object] patterns.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelEnsureDirectoryResult(BaseModel):
+    """Result from filesystem.ensure_directory operation.
+
+    Contains metadata about the directory creation operation.
+
+    Attributes:
+        path: The resolved absolute path to the directory.
+        created: True if the directory was created by this operation.
+        already_existed: True if the directory already existed before
+            this operation was called.
+
+    Example:
+        >>> result = ModelEnsureDirectoryResult(
+        ...     path="/data/output/reports",
+        ...     created=True,
+        ...     already_existed=False,
+        ... )
+        >>> print(result.created)
+        True
+
+        >>> existing_result = ModelEnsureDirectoryResult(
+        ...     path="/data/existing",
+        ...     created=False,
+        ...     already_existed=True,
+        ... )
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    path: str = Field(
+        min_length=1,
+        description="Resolved absolute path to the directory.",
+    )
+    created: bool = Field(
+        description="True if the directory was created by this operation.",
+    )
+    already_existed: bool = Field(
+        description="True if the directory already existed.",
+    )
+
+
+__all__: list[str] = ["ModelEnsureDirectoryResult"]

omnibase_infra/handlers/models/model_filesystem_list_directory_payload.py

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Filesystem List Directory Payload Model.
+
+This module provides the Pydantic model for the filesystem.list_directory operation
+payload, replacing untyped dict[str, object] patterns.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelListDirectoryPayload(BaseModel):
+    """Payload for filesystem.list_directory operation.
+
+    Specifies the directory to list and filtering options.
+
+    Attributes:
+        path: Absolute or relative path to the directory to list.
+            The path will be validated against the allowed_paths whitelist.
+        recursive: If True, recursively list subdirectories.
+            If False (default), only list immediate children.
+        pattern: Optional glob pattern to filter entries by name.
+            Uses fnmatch-style patterns (e.g., "*.py", "test_*").
+
+    Example:
+        >>> payload = ModelListDirectoryPayload(path="/data")
+        >>> print(payload.recursive)
+        False
+
+        >>> filtered_payload = ModelListDirectoryPayload(
+        ...     path="/src",
+        ...     recursive=True,
+        ...     pattern="*.py",
+        ... )
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    path: str = Field(
+        min_length=1,
+        description="Path to the directory to list. Validated against allowed_paths.",
+    )
+    recursive: bool = Field(
+        default=False,
+        description="If True, recursively list subdirectories.",
+    )
+    pattern: str | None = Field(
+        default=None,
+        description="Optional glob pattern to filter entries (fnmatch-style).",
+    )
+
+
+__all__: list[str] = ["ModelListDirectoryPayload"]

omnibase_infra/handlers/models/model_filesystem_list_directory_result.py

@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Filesystem List Directory Result Model.
+
+This module provides the Pydantic model for the filesystem.list_directory operation
+result, replacing untyped dict[str, object] patterns.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.handlers.models.model_filesystem_directory_entry import (
+    ModelDirectoryEntry,
+)
+
+
+class ModelListDirectoryResult(BaseModel):
+    """Result from filesystem.list_directory operation.
+
+    Contains the directory listing and metadata.
+
+    Attributes:
+        entries: List of directory entries matching the criteria.
+        count: Number of entries returned.
+        path: The resolved absolute path of the directory that was listed.
+
+    Example:
+        >>> result = ModelListDirectoryResult(
+        ...     entries=[
+        ...         ModelDirectoryEntry(
+        ...             name="file.txt",
+        ...             path="/data/file.txt",
+        ...             is_file=True,
+        ...             is_dir=False,
+        ...             is_symlink=False,
+        ...             size=100,
+        ...             modified=1704067200.0,
+        ...         ),
+        ...     ],
+        ...     count=1,
+        ...     path="/data",
+        ... )
+        >>> print(result.count)
+        1
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    entries: list[ModelDirectoryEntry] = Field(
+        description="List of directory entries.",
+    )
+    count: int = Field(
+        ge=0,
+        description="Number of entries returned.",
+    )
+    path: str = Field(
+        min_length=1,
+        description="Resolved absolute path of the directory.",
+    )
+
+
+__all__: list[str] = ["ModelListDirectoryResult"]

omnibase_infra/handlers/models/model_filesystem_read_payload.py

@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Filesystem Read File Payload Model.
+
+This module provides the Pydantic model for the filesystem.read_file operation
+payload, replacing untyped dict[str, object] patterns.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelReadFilePayload(BaseModel):
+    """Payload for filesystem.read_file operation.
+
+    Specifies the file to read and how to interpret its contents.
+
+    Attributes:
+        path: Absolute or relative path to the file to read.
+            The path will be validated against the allowed_paths whitelist.
+        binary: If True, read as binary and return base64-encoded content.
+            If False (default), read as text using the specified encoding.
+        encoding: Text encoding to use when binary=False.
+            Defaults to "utf-8". Ignored when binary=True.
+
+    Example:
+        >>> payload = ModelReadFilePayload(path="/data/config.json")
+        >>> print(payload.encoding)
+        'utf-8'
+
+        >>> binary_payload = ModelReadFilePayload(
+        ...     path="/data/image.png",
+        ...     binary=True,
+        ... )
+        >>> print(binary_payload.binary)
+        True
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    path: str = Field(
+        min_length=1,
+        description="Path to the file to read. Validated against allowed_paths.",
+    )
+    binary: bool = Field(
+        default=False,
+        description="If True, read as binary and return base64-encoded content.",
+    )
+    encoding: str = Field(
+        default="utf-8",
+        min_length=1,
+        description="Text encoding for non-binary reads. Ignored when binary=True.",
+    )
+
+
+__all__: list[str] = ["ModelReadFilePayload"]

omnibase_infra/handlers/models/model_filesystem_read_result.py

@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Filesystem Read File Result Model.
+
+This module provides the Pydantic model for the filesystem.read_file operation
+result, replacing untyped dict[str, object] patterns.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelReadFileResult(BaseModel):
+    """Result from filesystem.read_file operation.
+
+    Contains the file content and metadata about the read operation.
+
+    Attributes:
+        content: The file content. For binary=True, this is a base64-encoded
+            string. For binary=False, this is the decoded text content.
+        size: Size of the file in bytes (original size, not encoded size).
+        path: The resolved absolute path to the file that was read.
+        binary: Whether the file was read in binary mode.
+
+    Example:
+        >>> result = ModelReadFileResult(
+        ...     content="Hello, World!",
+        ...     size=13,
+        ...     path="/data/greeting.txt",
+        ...     binary=False,
+        ... )
+        >>> print(result.size)
+        13
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    content: str = Field(
+        description="File content. Base64-encoded for binary mode, "
+        "text for non-binary mode.",
+    )
+    size: int = Field(
+        ge=0,
+        description="File size in bytes.",
+    )
+    path: str = Field(
+        min_length=1,
+        description="Resolved absolute path to the file.",
+    )
+    binary: bool = Field(
+        description="Whether the file was read in binary mode.",
+    )
+
+
+__all__: list[str] = ["ModelReadFileResult"]

omnibase_infra/handlers/models/model_filesystem_write_payload.py

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Filesystem Write File Payload Model.
+
+This module provides the Pydantic model for the filesystem.write_file operation
+payload, replacing untyped dict[str, object] patterns.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelWriteFilePayload(BaseModel):
+    """Payload for filesystem.write_file operation.
+
+    Specifies the file to write and the content to write.
+
+    Attributes:
+        path: Absolute or relative path to the file to write.
+            The path will be validated against the allowed_paths whitelist.
+        content: Content to write. For binary=True, this should be a
+            base64-encoded string. For binary=False, this is plain text.
+        binary: If True, decode content from base64 and write as binary.
+            If False (default), write as text.
+        create_dirs: If True, create parent directories if they don't exist.
+            If False (default), fail if parent directory doesn't exist.
+
+    Example:
+        >>> payload = ModelWriteFilePayload(
+        ...     path="/data/output.txt",
+        ...     content="Hello, World!",
+        ... )
+        >>> print(payload.create_dirs)
+        False
+
+        >>> binary_payload = ModelWriteFilePayload(
+        ...     path="/data/image.png",
+        ...     content="iVBORw0KGgo...",  # base64 encoded
+        ...     binary=True,
+        ...     create_dirs=True,
+        ... )
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    path: str = Field(
+        min_length=1,
+        description="Path to the file to write. Validated against allowed_paths.",
+    )
+    content: str = Field(
+        description="Content to write. Base64-encoded for binary mode, "
+        "plain text for non-binary mode.",
+    )
+    binary: bool = Field(
+        default=False,
+        description="If True, decode content from base64 and write as binary.",
+    )
+    create_dirs: bool = Field(
+        default=False,
+        description="If True, create parent directories if they don't exist.",
+    )
+
+
+__all__: list[str] = ["ModelWriteFilePayload"]

omnibase_infra/handlers/models/model_filesystem_write_result.py

@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Filesystem Write File Result Model.
+
+This module provides the Pydantic model for the filesystem.write_file operation
+result, replacing untyped dict[str, object] patterns.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelWriteFileResult(BaseModel):
+    """Result from filesystem.write_file operation.
+
+    Contains metadata about the completed write operation.
+
+    Attributes:
+        path: The resolved absolute path to the file that was written.
+        bytes_written: Number of bytes written to the file.
+        created: True if a new file was created, False if an existing
+            file was overwritten.
+
+    Example:
+        >>> result = ModelWriteFileResult(
+        ...     path="/data/output.txt",
+        ...     bytes_written=13,
+        ...     created=True,
+        ... )
+        >>> print(result.created)
+        True
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    path: str = Field(
+        min_length=1,
+        description="Resolved absolute path to the file.",
+    )
+    bytes_written: int = Field(
+        ge=0,
+        description="Number of bytes written to the file.",
+    )
+    created: bool = Field(
+        description="True if a new file was created, False if overwritten.",
+    )
+
+
+__all__: list[str] = ["ModelWriteFileResult"]