pylaag-core 0.1.0__tar.gz

pylaag_core-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# uv
+.uv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.hypothesis/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Build artifacts
+*.whl
+*.tar.gz

pylaag_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 B Schwarz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pylaag_core-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: pylaag-core
+Version: 0.1.0
+Summary: Core utilities and base classes for the laag Python library
+Project-URL: Homepage, https://github.com/laag/laag-python
+Project-URL: Repository, https://github.com/laag/laag-python
+Project-URL: Documentation, https://github.com/laag/laag-python#readme
+Project-URL: Bug Tracker, https://github.com/laag/laag-python/issues
+Author: Laag Contributors
+License: MIT
+License-File: LICENSE
+Keywords: api,api-design,api-documentation,openapi,raml,smithy,specification,swagger
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# pylaag-core
+
+Core utilities and base classes for the laag Python library.
+
+## Overview
+
+`pylaag-core` provides the foundational components used by all laag packages, including:
+
+- Base classes for API document handlers
+- Error handling system
+- Utility functions for nested object navigation
+- Extension property support
+
+This package is typically installed as a dependency of other laag packages and is not used directly in most cases.
+
+## Installation
+
+```bash
+pip install pylaag-core
+```
+
+## Features
+
+- **LaagBase**: Abstract base class for all API document handlers
+- **Error Classes**: Comprehensive exception hierarchy (LaagError, ValidationError, ParseError, NotFoundError)
+- **Utility Functions**: Helper functions for working with nested dictionaries
+- **Extension Properties**: Support for x-* custom properties in API documents
+- **Type Safety**: Full type hints for static analysis
+
+## Usage
+
+### Base Class
+
+```python
+from pylaag_core import LaagBase
+
+class MyDocument(LaagBase):
+    def validate(self) -> None:
+        # Implement validation logic
+        if 'required_field' not in self._document:
+            raise ValidationError("Missing required field")
+```
+
+### Error Handling
+
+```python
+from pylaag_core import ValidationError, ParseError, NotFoundError
+
+try:
+    doc.validate()
+except ValidationError as e:
+    print(f"Validation failed: {e}")
+    print(f"Context: {e.context}")
+```
+
+### Utility Functions
+
+```python
+from pylaag_core import get_nested, set_nested, delete_nested
+
+data = {'a': {'b': {'c': 1}}}
+
+# Get nested value
+value = get_nested(data, 'a.b.c')  # Returns 1
+
+# Set nested value
+set_nested(data, 'a.b.d', 2)  # data['a']['b']['d'] = 2
+
+# Delete nested value
+deleted = delete_nested(data, 'a.b.c')  # Returns True
+```
+
+### Extension Properties
+
+```python
+from pylaag_core import LaagBase
+
+doc = MyDocument()
+
+# Set extension property
+doc.set_extension('x-custom', {'key': 'value'})
+
+# Get extension property
+custom = doc.get_extension('x-custom')
+
+# Remove extension property
+doc.remove_extension('x-custom')
+```
+
+## API Reference
+
+### Classes
+
+#### LaagBase
+
+Abstract base class for all API document handlers.
+
+**Methods:**
+- `validate() -> None`: Validate the document (must be implemented by subclasses)
+- `get_extension(key: str) -> Optional[Any]`: Get an extension property value
+- `set_extension(key: str, value: Any) -> None`: Set an extension property value
+- `remove_extension(key: str) -> None`: Remove an extension property
+- `to_dict() -> Dict[str, Any]`: Convert to dictionary representation
+
+#### LaagError
+
+Base exception class for all laag errors.
+
+**Attributes:**
+- `context: Dict[str, Any]`: Additional context information about the error
+
+#### ValidationError
+
+Raised when document validation fails.
+
+#### ParseError
+
+Raised when document parsing fails.
+
+#### NotFoundError
+
+Raised when a requested resource is not found.
+
+### Functions
+
+#### get_nested
+
+```python
+def get_nested(obj: Dict[str, Any], path: str, default: Any = None) -> Any
+```
+
+Get a nested value from a dictionary using dot notation.
+
+**Parameters:**
+- `obj`: The dictionary to search
+- `path`: Dot-separated path (e.g., 'a.b.c')
+- `default`: Default value if path not found
+
+**Returns:** The value at the path, or default if not found
+
+#### set_nested
+
+```python
+def set_nested(obj: Dict[str, Any], path: str, value: Any) -> None
+```
+
+Set a nested value in a dictionary using dot notation.
+
+**Parameters:**
+- `obj`: The dictionary to modify
+- `path`: Dot-separated path (e.g., 'a.b.c')
+- `value`: Value to set
+
+#### delete_nested
+
+```python
+def delete_nested(obj: Dict[str, Any], path: str) -> bool
+```
+
+Delete a nested value from a dictionary using dot notation.
+
+**Parameters:**
+- `obj`: The dictionary to modify
+- `path`: Dot-separated path (e.g., 'a.b.c')
+
+**Returns:** True if the value was deleted, False if not found
+
+## Requirements
+
+- Python 3.10 or higher
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Related Packages
+
+- [pylaag-openapi](https://pypi.org/project/pylaag-openapi/) - OpenAPI/Swagger support
+- [pylaag-raml](https://pypi.org/project/pylaag-raml/) - RAML support
+- [pylaag-smithy](https://pypi.org/project/pylaag-smithy/) - Smithy support

pylaag_core-0.1.0/README.md

@@ -0,0 +1,180 @@
+# pylaag-core
+
+Core utilities and base classes for the laag Python library.
+
+## Overview
+
+`pylaag-core` provides the foundational components used by all laag packages, including:
+
+- Base classes for API document handlers
+- Error handling system
+- Utility functions for nested object navigation
+- Extension property support
+
+This package is typically installed as a dependency of other laag packages and is not used directly in most cases.
+
+## Installation
+
+```bash
+pip install pylaag-core
+```
+
+## Features
+
+- **LaagBase**: Abstract base class for all API document handlers
+- **Error Classes**: Comprehensive exception hierarchy (LaagError, ValidationError, ParseError, NotFoundError)
+- **Utility Functions**: Helper functions for working with nested dictionaries
+- **Extension Properties**: Support for x-* custom properties in API documents
+- **Type Safety**: Full type hints for static analysis
+
+## Usage
+
+### Base Class
+
+```python
+from pylaag_core import LaagBase
+
+class MyDocument(LaagBase):
+    def validate(self) -> None:
+        # Implement validation logic
+        if 'required_field' not in self._document:
+            raise ValidationError("Missing required field")
+```
+
+### Error Handling
+
+```python
+from pylaag_core import ValidationError, ParseError, NotFoundError
+
+try:
+    doc.validate()
+except ValidationError as e:
+    print(f"Validation failed: {e}")
+    print(f"Context: {e.context}")
+```
+
+### Utility Functions
+
+```python
+from pylaag_core import get_nested, set_nested, delete_nested
+
+data = {'a': {'b': {'c': 1}}}
+
+# Get nested value
+value = get_nested(data, 'a.b.c')  # Returns 1
+
+# Set nested value
+set_nested(data, 'a.b.d', 2)  # data['a']['b']['d'] = 2
+
+# Delete nested value
+deleted = delete_nested(data, 'a.b.c')  # Returns True
+```
+
+### Extension Properties
+
+```python
+from pylaag_core import LaagBase
+
+doc = MyDocument()
+
+# Set extension property
+doc.set_extension('x-custom', {'key': 'value'})
+
+# Get extension property
+custom = doc.get_extension('x-custom')
+
+# Remove extension property
+doc.remove_extension('x-custom')
+```
+
+## API Reference
+
+### Classes
+
+#### LaagBase
+
+Abstract base class for all API document handlers.
+
+**Methods:**
+- `validate() -> None`: Validate the document (must be implemented by subclasses)
+- `get_extension(key: str) -> Optional[Any]`: Get an extension property value
+- `set_extension(key: str, value: Any) -> None`: Set an extension property value
+- `remove_extension(key: str) -> None`: Remove an extension property
+- `to_dict() -> Dict[str, Any]`: Convert to dictionary representation
+
+#### LaagError
+
+Base exception class for all laag errors.
+
+**Attributes:**
+- `context: Dict[str, Any]`: Additional context information about the error
+
+#### ValidationError
+
+Raised when document validation fails.
+
+#### ParseError
+
+Raised when document parsing fails.
+
+#### NotFoundError
+
+Raised when a requested resource is not found.
+
+### Functions
+
+#### get_nested
+
+```python
+def get_nested(obj: Dict[str, Any], path: str, default: Any = None) -> Any
+```
+
+Get a nested value from a dictionary using dot notation.
+
+**Parameters:**
+- `obj`: The dictionary to search
+- `path`: Dot-separated path (e.g., 'a.b.c')
+- `default`: Default value if path not found
+
+**Returns:** The value at the path, or default if not found
+
+#### set_nested
+
+```python
+def set_nested(obj: Dict[str, Any], path: str, value: Any) -> None
+```
+
+Set a nested value in a dictionary using dot notation.
+
+**Parameters:**
+- `obj`: The dictionary to modify
+- `path`: Dot-separated path (e.g., 'a.b.c')
+- `value`: Value to set
+
+#### delete_nested
+
+```python
+def delete_nested(obj: Dict[str, Any], path: str) -> bool
+```
+
+Delete a nested value from a dictionary using dot notation.
+
+**Parameters:**
+- `obj`: The dictionary to modify
+- `path`: Dot-separated path (e.g., 'a.b.c')
+
+**Returns:** True if the value was deleted, False if not found
+
+## Requirements
+
+- Python 3.10 or higher
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Related Packages
+
+- [pylaag-openapi](https://pypi.org/project/pylaag-openapi/) - OpenAPI/Swagger support
+- [pylaag-raml](https://pypi.org/project/pylaag-raml/) - RAML support
+- [pylaag-smithy](https://pypi.org/project/pylaag-smithy/) - Smithy support

pylaag_core-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "pylaag-core"
+version = "0.1.0"
+description = "Core utilities and base classes for the laag Python library"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Laag Contributors" }
+]
+keywords = [
+    "api",
+    "specification",
+    "openapi",
+    "swagger",
+    "raml",
+    "smithy",
+    "api-design",
+    "api-documentation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/laag/laag-python"
+Repository = "https://github.com/laag/laag-python"
+Documentation = "https://github.com/laag/laag-python#readme"
+"Bug Tracker" = "https://github.com/laag/laag-python/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pylaag_core"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["tests/"]

pylaag_core-0.1.0/src/pylaag_core/__init__.py

@@ -0,0 +1,18 @@
+"""Core utilities and base classes for the laag Python library."""
+
+__version__ = "0.1.0"
+
+from pylaag_core.base import LaagBase
+from pylaag_core.errors import LaagError, NotFoundError, ParseError, ValidationError
+from pylaag_core.utils import delete_nested, get_nested, set_nested
+
+__all__ = [
+    "LaagBase",
+    "LaagError",
+    "ValidationError",
+    "ParseError",
+    "NotFoundError",
+    "get_nested",
+    "set_nested",
+    "delete_nested",
+]

pylaag_core-0.1.0/src/pylaag_core/base.py

@@ -0,0 +1,82 @@
+"""Base class for all API document handlers."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class LaagBase(ABC, Generic[T]):
+    """Base class for all API document handlers.
+
+    This class provides common functionality for managing API documents,
+    including extension property handling and document serialization.
+    """
+
+    def __init__(self, document: dict[str, Any] | None = None):
+        """Initialize the base document handler.
+
+        Args:
+            document: The document dictionary to manage. If None, an empty dict is used.
+        """
+        self._document: dict[str, Any] = document or {}
+        self._extensions: dict[str, Any] = {}
+        self._extract_extensions()
+
+    @abstractmethod
+    def validate(self) -> None:
+        """Validate the document against its specification.
+
+        Raises:
+            ValidationError: If the document is invalid
+        """
+        pass
+
+    def _extract_extensions(self) -> None:
+        """Extract x-* properties from document into the extensions dict."""
+        for key, value in list(self._document.items()):
+            if key.startswith("x-"):
+                self._extensions[key] = value
+
+    def get_extension(self, key: str) -> Any | None:
+        """Get an extension property value.
+
+        Args:
+            key: The extension property key (should start with 'x-')
+
+        Returns:
+            The extension property value, or None if not found
+        """
+        return self._extensions.get(key)
+
+    def set_extension(self, key: str, value: Any) -> None:
+        """Set an extension property value.
+
+        Args:
+            key: The extension property key (must start with 'x-')
+            value: The value to set
+
+        Raises:
+            ValueError: If the key does not start with 'x-'
+        """
+        if not key.startswith("x-"):
+            raise ValueError(f"Extension property must start with 'x-': {key}")
+        self._extensions[key] = value
+        self._document[key] = value
+
+    def remove_extension(self, key: str) -> None:
+        """Remove an extension property.
+
+        Args:
+            key: The extension property key to remove
+        """
+        self._extensions.pop(key, None)
+        self._document.pop(key, None)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary representation.
+
+        Returns:
+            A copy of the document dictionary
+        """
+        return self._document.copy()

pylaag_core-0.1.0/src/pylaag_core/errors.py

@@ -0,0 +1,29 @@
+"""Error classes for the laag Python library."""
+
+from typing import Any
+
+
+class LaagError(Exception):
+    """Base exception for all laag errors."""
+
+    def __init__(self, message: str, context: dict[str, Any] | None = None):
+        super().__init__(message)
+        self.context = context or {}
+
+
+class ValidationError(LaagError):
+    """Raised when document validation fails."""
+
+    pass
+
+
+class ParseError(LaagError):
+    """Raised when document parsing fails."""
+
+    pass
+
+
+class NotFoundError(LaagError):
+    """Raised when a requested resource is not found."""
+
+    pass

pylaag_core-0.1.0/src/pylaag_core/utils.py

@@ -0,0 +1,88 @@
+"""Utility functions for the laag Python library."""
+
+from typing import Any
+
+
+def get_nested(obj: dict[str, Any], path: str, default: Any = None) -> Any:
+    """Get a nested value from a dictionary using dot notation.
+
+    Args:
+        obj: The dictionary to search
+        path: Dot-separated path to the value (e.g., 'a.b.c')
+        default: Default value to return if path not found
+
+    Returns:
+        The value at the specified path, or default if not found
+
+    Example:
+        >>> get_nested({'a': {'b': {'c': 1}}}, 'a.b.c')
+        1
+        >>> get_nested({'a': {'b': {}}}, 'a.b.c', 'not found')
+        'not found'
+    """
+    keys = path.split(".")
+    current = obj
+
+    for key in keys:
+        if not isinstance(current, dict) or key not in current:
+            return default
+        current = current[key]
+
+    return current
+
+
+def set_nested(obj: dict[str, Any], path: str, value: Any) -> None:
+    """Set a nested value in a dictionary using dot notation.
+
+    Args:
+        obj: The dictionary to modify
+        path: Dot-separated path to the value (e.g., 'a.b.c')
+        value: The value to set
+
+    Example:
+        >>> d = {}
+        >>> set_nested(d, 'a.b.c', 1)
+        >>> d
+        {'a': {'b': {'c': 1}}}
+    """
+    keys = path.split(".")
+    current = obj
+
+    for key in keys[:-1]:
+        if key not in current:
+            current[key] = {}
+        current = current[key]
+
+    current[keys[-1]] = value
+
+
+def delete_nested(obj: dict[str, Any], path: str) -> bool:
+    """Delete a nested value from a dictionary using dot notation.
+
+    Args:
+        obj: The dictionary to modify
+        path: Dot-separated path to the value (e.g., 'a.b.c')
+
+    Returns:
+        True if the value was deleted, False if not found
+
+    Example:
+        >>> d = {'a': {'b': {'c': 1}}}
+        >>> delete_nested(d, 'a.b.c')
+        True
+        >>> delete_nested(d, 'a.b.c')
+        False
+    """
+    keys = path.split(".")
+    current = obj
+
+    for key in keys[:-1]:
+        if not isinstance(current, dict) or key not in current:
+            return False
+        current = current[key]
+
+    if keys[-1] in current:
+        del current[keys[-1]]
+        return True
+
+    return False