wexample-api 0.0.74__tar.gz

wexample_api-0.0.74/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.1
+Name: wexample-api
+Version: 0.0.74
+Summary: Some python basic helpers for apis.
+Author-Email: weeger <contact@wexample.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Project-URL: homepage, https://github.com/wexample/python-api
+Requires-Python: >=3.10
+Requires-Dist: attrs>=23.1.0
+Requires-Dist: cattrs>=23.1.0
+Requires-Dist: requests
+Requires-Dist: wexample-helpers==0.0.78
+Requires-Dist: wexample-prompt==0.0.90
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Description-Content-Type: text/markdown
+
+# wexample-api
+
+Version: 0.0.74
+
+Some python basic helpers for apis.
+
+## Tests
+
+This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.
+
+### Installation
+
+First, install the required testing dependencies:
+```bash
+.venv/bin/python -m pip install pytest pytest-cov
+```
+
+### Basic Usage
+
+Run all tests with coverage:
+```bash
+.venv/bin/python -m pytest --cov --cov-report=html
+```
+
+### Common Commands
+```bash
+# Run tests with coverage for a specific module
+.venv/bin/python -m pytest --cov=your_module
+
+# Show which lines are not covered
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing
+
+# Generate an HTML coverage report
+.venv/bin/python -m pytest --cov=your_module --cov-report=html
+
+# Combine terminal and HTML reports
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html
+
+# Run specific test file with coverage
+.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
+```
+
+### Viewing HTML Reports
+
+After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.
+
+### Coverage Threshold
+
+To enforce a minimum coverage percentage:
+```bash
+.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
+```
+
+This will cause the test suite to fail if coverage drops below 80%.
+
+## Code Quality & Typing
+
+All the suite packages follow strict quality standards:
+
+- **Type hints**: Full type coverage with mypy validation
+- **Code formatting**: Enforced with black and isort
+- **Linting**: Comprehensive checks with custom scripts and tools
+- **Testing**: High test coverage requirements
+
+These standards ensure reliability and maintainability across the suite.
+
+## Versioning & Compatibility Policy
+
+Wexample packages follow **Semantic Versioning** (SemVer):
+
+- **MAJOR**: Breaking changes
+- **MINOR**: New features, backward compatible
+- **PATCH**: Bug fixes, backward compatible
+
+We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for detailed version history and release notes.
+
+Major changes are documented with migration guides when applicable.
+
+## Migration Notes
+
+When upgrading between major versions, refer to the migration guides in the documentation.
+
+Breaking changes are clearly documented with upgrade paths and examples.
+
+## Known Limitations & Roadmap
+
+Current limitations and planned features are tracked in the GitHub issues.
+
+See the [project roadmap](https://github.com/wexample/python-api/issues) for upcoming features and improvements.
+
+## Security Policy
+
+### Reporting Vulnerabilities
+
+If you discover a security vulnerability, please email security@wexample.com.
+
+**Do not** open public issues for security vulnerabilities.
+
+We take security seriously and will respond promptly to verified reports.
+
+## Privacy & Telemetry
+
+This package does **not** collect any telemetry or usage data.
+
+Your privacy is respected — no data is transmitted to external services.
+
+## Support Channels
+
+- **GitHub Issues**: Bug reports and feature requests
+- **GitHub Discussions**: Questions and community support
+- **Documentation**: Comprehensive guides and API reference
+- **Email**: contact@wexample.com for general inquiries
+
+Community support is available through GitHub Discussions.
+
+## Contribution Guidelines
+
+We welcome contributions to the Wexample suite! 
+
+### How to Contribute
+
+1. **Fork** the repository
+2. **Create** a feature branch
+3. **Make** your changes
+4. **Test** thoroughly
+5. **Submit** a pull request
+
+## Maintainers & Authors
+
+Maintained by the Wexample team and community contributors.
+
+See [CONTRIBUTORS.md](CONTRIBUTORS.md) for the full list of contributors.
+
+## License
+
+MIT
+
+## Useful Links
+
+- **Homepage**: https://github.com/wexample/python-api
+- **Documentation**: [docs.wexample.com](https://docs.wexample.com)
+- **Issue Tracker**: https://github.com/wexample/python-api/issues
+- **Discussions**: https://github.com/wexample/python-api/discussions
+- **PyPI**: [pypi.org/project/wexample-api](https://pypi.org/project/wexample-api/)
+
+## Integration in the Suite
+
+This package is part of the **Wexample Suite** — a collection of high-quality Python packages designed to work seamlessly together.
+
+### Related Packages
+
+The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.
+
+Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.
+
+# About us
+
+Wexample stands as a cornerstone of the digital ecosystem — a collective of seasoned engineers, researchers, and creators driven by a relentless pursuit of technological excellence. More than a media platform, it has grown into a vibrant community where innovation meets craftsmanship, and where every line of code reflects a commitment to clarity, durability, and shared intelligence.
+
+This packages suite embodies this spirit. Trusted by professionals and enthusiasts alike, it delivers a consistent, high-quality foundation for modern development — open, elegant, and battle-tested. Its reputation is built on years of collaboration, refinement, and rigorous attention to detail, making it a natural choice for those who demand both robustness and beauty in their tools.
+
+Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.
+

wexample_api-0.0.74/README.md

@@ -0,0 +1,167 @@
+# wexample-api
+
+Version: 0.0.74
+
+Some python basic helpers for apis.
+
+## Tests
+
+This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.
+
+### Installation
+
+First, install the required testing dependencies:
+```bash
+.venv/bin/python -m pip install pytest pytest-cov
+```
+
+### Basic Usage
+
+Run all tests with coverage:
+```bash
+.venv/bin/python -m pytest --cov --cov-report=html
+```
+
+### Common Commands
+```bash
+# Run tests with coverage for a specific module
+.venv/bin/python -m pytest --cov=your_module
+
+# Show which lines are not covered
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing
+
+# Generate an HTML coverage report
+.venv/bin/python -m pytest --cov=your_module --cov-report=html
+
+# Combine terminal and HTML reports
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html
+
+# Run specific test file with coverage
+.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
+```
+
+### Viewing HTML Reports
+
+After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.
+
+### Coverage Threshold
+
+To enforce a minimum coverage percentage:
+```bash
+.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
+```
+
+This will cause the test suite to fail if coverage drops below 80%.
+
+## Code Quality & Typing
+
+All the suite packages follow strict quality standards:
+
+- **Type hints**: Full type coverage with mypy validation
+- **Code formatting**: Enforced with black and isort
+- **Linting**: Comprehensive checks with custom scripts and tools
+- **Testing**: High test coverage requirements
+
+These standards ensure reliability and maintainability across the suite.
+
+## Versioning & Compatibility Policy
+
+Wexample packages follow **Semantic Versioning** (SemVer):
+
+- **MAJOR**: Breaking changes
+- **MINOR**: New features, backward compatible
+- **PATCH**: Bug fixes, backward compatible
+
+We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for detailed version history and release notes.
+
+Major changes are documented with migration guides when applicable.
+
+## Migration Notes
+
+When upgrading between major versions, refer to the migration guides in the documentation.
+
+Breaking changes are clearly documented with upgrade paths and examples.
+
+## Known Limitations & Roadmap
+
+Current limitations and planned features are tracked in the GitHub issues.
+
+See the [project roadmap](https://github.com/wexample/python-api/issues) for upcoming features and improvements.
+
+## Security Policy
+
+### Reporting Vulnerabilities
+
+If you discover a security vulnerability, please email security@wexample.com.
+
+**Do not** open public issues for security vulnerabilities.
+
+We take security seriously and will respond promptly to verified reports.
+
+## Privacy & Telemetry
+
+This package does **not** collect any telemetry or usage data.
+
+Your privacy is respected — no data is transmitted to external services.
+
+## Support Channels
+
+- **GitHub Issues**: Bug reports and feature requests
+- **GitHub Discussions**: Questions and community support
+- **Documentation**: Comprehensive guides and API reference
+- **Email**: contact@wexample.com for general inquiries
+
+Community support is available through GitHub Discussions.
+
+## Contribution Guidelines
+
+We welcome contributions to the Wexample suite! 
+
+### How to Contribute
+
+1. **Fork** the repository
+2. **Create** a feature branch
+3. **Make** your changes
+4. **Test** thoroughly
+5. **Submit** a pull request
+
+## Maintainers & Authors
+
+Maintained by the Wexample team and community contributors.
+
+See [CONTRIBUTORS.md](CONTRIBUTORS.md) for the full list of contributors.
+
+## License
+
+MIT
+
+## Useful Links
+
+- **Homepage**: https://github.com/wexample/python-api
+- **Documentation**: [docs.wexample.com](https://docs.wexample.com)
+- **Issue Tracker**: https://github.com/wexample/python-api/issues
+- **Discussions**: https://github.com/wexample/python-api/discussions
+- **PyPI**: [pypi.org/project/wexample-api](https://pypi.org/project/wexample-api/)
+
+## Integration in the Suite
+
+This package is part of the **Wexample Suite** — a collection of high-quality Python packages designed to work seamlessly together.
+
+### Related Packages
+
+The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.
+
+Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.
+
+# About us
+
+Wexample stands as a cornerstone of the digital ecosystem — a collective of seasoned engineers, researchers, and creators driven by a relentless pursuit of technological excellence. More than a media platform, it has grown into a vibrant community where innovation meets craftsmanship, and where every line of code reflects a commitment to clarity, durability, and shared intelligence.
+
+This packages suite embodies this spirit. Trusted by professionals and enthusiasts alike, it delivers a consistent, high-quality foundation for modern development — open, elegant, and battle-tested. Its reputation is built on years of collaboration, refinement, and rigorous attention to detail, making it a natural choice for those who demand both robustness and beauty in their tools.
+
+Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.
+

wexample_api-0.0.74/pyproject.toml

@@ -0,0 +1,88 @@
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[project]
+name = "wexample-api"
+version = "0.0.74"
+description = "Some python basic helpers for apis."
+authors = [
+    { name = "weeger", email = "contact@wexample.com" },
+]
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "attrs>=23.1.0",
+    "cattrs>=23.1.0",
+    "requests",
+    "wexample-helpers==0.0.78",
+    "wexample-prompt==0.0.90",
+]
+
+[project.readme]
+file = "README.md"
+content-type = "text/markdown"
+
+[project.license]
+text = "MIT"
+
+[project.urls]
+homepage = "https://github.com/wexample/python-api"
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-cov",
+]
+
+[tool.setuptools.packages.find]
+include = [
+    "*",
+]
+exclude = [
+    "wexample_api.testing*",
+]
+
+[tool.pdm]
+distribution = true
+
+[tool.pdm.build]
+package-dir = "src"
+packages = [
+    { include = "wexample_api", from = "src" },
+]
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+]
+pythonpath = [
+    "src",
+]
+
+[tool.coverage.run]
+source = [
+    "wexample_api",
+]
+omit = [
+    "*/tests/*",
+    "*/.venv/*",
+    "*/venv/*",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "@abstractmethod",
+]

wexample_api-0.0.74/src/wexample_api/common/abstract_gateway.py

@@ -0,0 +1,333 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any
+
+import requests
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.classes.mixin.has_snake_short_class_name_class_mixin import (
+    HasSnakeShortClassNameClassMixin,
+)
+from wexample_helpers.classes.mixin.has_two_steps_init import HasTwoStepInit
+from wexample_helpers.decorator.base_class import base_class
+from wexample_prompt.mixins.with_io_manager import WithIoManager
+
+from wexample_api.enums.http import ContentType, HttpMethod
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from wexample_helpers.const.types import StringsList
+
+    from wexample_api.common.http_request_payload import HttpRequestPayload
+    from wexample_api.enums.http import Header
+
+
+@base_class
+class AbstractGateway(
+    HasSnakeShortClassNameClassMixin,
+    WithIoManager,
+    HasTwoStepInit,
+):
+    # Base configuration
+    base_url: str | None = public_field(default=None, description="Base API URL")
+    # State
+    connected: bool = public_field(default=False, description="Connection state")
+    # Default request configuration
+    default_headers: dict[str, str] = public_field(
+        factory=dict, description="Default headers for requests"
+    )
+    last_exception: Any = public_field(
+        default=None, description="Last exception encountered during request"
+    )
+    last_request_time: float | None = public_field(
+        default=None, description="Timestamp of last request"
+    )
+    quiet: bool = public_field(
+        default=False, description="If True, only show errors and warnings"
+    )
+    rate_limit_delay: float = public_field(
+        default=1.0, description="Minimum delay between requests in seconds"
+    )
+    timeout: int = public_field(default=30, description="Request timeout in seconds")
+
+    @classmethod
+    def get_class_name_suffix(cls) -> str | None:
+        return "GatewayService"
+
+    def check_connexion(self) -> bool:
+        return self.connected
+
+    def check_status_code(self, expected_status_codes: int | list[int] = 200) -> bool:
+        return (
+            self.make_request(
+                endpoint="", expected_status_codes=expected_status_codes, quiet=True
+            )
+            is not None
+        )
+
+    def clear_error(self) -> None:
+        self.last_exception = None
+
+    def connect(self) -> bool:
+        self.connected = True
+        return True
+
+    def format_response_content(self, response: requests.Response | None) -> str:
+        """Extract and format response content for logging."""
+        if response is None:
+            return "Null response"
+
+        try:
+            return response.json()
+        except (ValueError, AttributeError):
+            return response.text
+
+    def get_base_url(self) -> str | None:
+        return self.base_url
+
+    def get_expected_env_keys(self) -> StringsList:
+        return []
+
+    def get_last_error(self) -> Exception | None:
+        return self.last_exception
+
+    def handle_api_response(
+        self,
+        response: requests.Response | None,
+        request_context: HttpRequestPayload,
+        exception: Exception | None = None,
+        fatal_on_error: bool = False,
+        quiet: bool | None = None,
+    ) -> requests.Response | None:
+        self.last_exception = exception
+        is_quiet = self.quiet if quiet is None else quiet
+
+        if response is None:
+            if not is_quiet:
+                self.io.properties(
+                    self._create_request_details(request_context),
+                    title="Request Details",
+                )
+            if exception:
+                self.io.error(str(exception), exception=exception, fatal=fatal_on_error)
+            return None
+
+        if not is_quiet:
+            self.io.debug(
+                message=f"{request_context.method} | {response.status_code} -> {request_context.url}",
+                symbol="🌍",
+            )
+
+        # If no filtering is configured, accept all responses
+        if request_context.expected_status_codes is None:
+            return response
+
+        if response.status_code in request_context.expected_status_codes:
+            return response
+
+        # Combine request details with response content
+        details = {
+            **self._create_request_details(request_context, response.status_code),
+            "Response Content": self.format_response_content(response),
+        }
+
+        if not is_quiet:
+            self.io.properties(details, title="Request Details")
+
+        self.io.error(
+            message=(
+                str(exception) if exception else self._extract_error_message(response)
+            ),
+            exception=exception,
+            fatal=fatal_on_error,
+        )
+        return response
+
+    def has_error(self) -> bool:
+        return self.last_exception is not None
+
+    def make_request(
+        self,
+        endpoint: str,
+        method: HttpMethod = HttpMethod.GET,
+        data: dict[str, Any] | bytes | None = None,
+        query_params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        files: dict[str, Any] | list[tuple] | None = None,
+        call_origin: str | None = None,
+        expected_status_codes: int | list[int] | None = None,
+        fatal_if_unexpected: bool = False,
+        quiet: bool = False,
+        stream: bool = False,
+        timeout: int | None = None,
+        raise_exceptions: bool = False,
+    ) -> requests.Response | None:
+        from wexample_helpers.errors.gateway_error import GatewayError
+
+        from wexample_api.common.http_request_payload import HttpRequestPayload
+        from wexample_api.enums.http import Header
+
+        payload = HttpRequestPayload.from_endpoint(
+            base_url=self.get_base_url(),
+            endpoint=endpoint,
+            method=method,
+            data=data,
+            query_params=query_params,
+            headers={**self.default_headers, **(headers or {})},
+            call_origin=call_origin,
+            expected_status_codes=expected_status_codes,
+        )
+
+        if not self.connected:
+            self.connect()
+
+        self._handle_rate_limiting()
+
+        # Determine how to send the data based on Content-Type header
+        content_type = self._get_header_value(payload.headers, Header.CONTENT_TYPE)
+
+        if files:
+            content_type = ContentType.MULTIPART.value
+            payload.headers.pop(Header.CONTENT_TYPE.value, None)
+
+        if payload.data is not None:
+            if isinstance(payload.data, bytes):
+                self.io.log(f"Sending binary payload ({len(payload.data)} bytes)")
+            else:
+                self.io.log(f"Sending {type(payload.data).__name__} payload")
+
+        request_kwargs: dict[str, Any] = {
+            "method": payload.method.value,
+            "url": payload.url,
+            "params": payload.query_params,
+            "headers": payload.headers,
+            "timeout": timeout or self.timeout,
+            "stream": stream,
+        }
+
+        if files:
+            request_kwargs["data"] = data or {}
+            request_kwargs["files"] = files
+        elif content_type in (
+            ContentType.FORM_URLENCODED.value,
+            ContentType.OCTET_STREAM.value,
+            ContentType.TEXT.value,
+        ):
+            request_kwargs["data"] = data
+        else:
+            request_kwargs["json"] = data
+
+        try:
+            response = requests.request(**request_kwargs)
+        except requests.exceptions.RequestException as exc:
+            gateway_error = GatewayError(f"Request failed: {exc}")
+            gateway_error.__cause__ = exc
+
+            if raise_exceptions:
+                raise gateway_error
+
+            return self.handle_api_response(
+                response=None,
+                request_context=payload,
+                exception=gateway_error,
+                fatal_on_error=fatal_if_unexpected,
+                quiet=quiet,
+            )
+
+        # Only check status code if expected_status_codes is explicitly provided
+        exception = None
+        if expected_status_codes is not None:
+            expected = (
+                {expected_status_codes}
+                if isinstance(expected_status_codes, int)
+                else set(expected_status_codes)
+            )
+            if response.status_code not in expected:
+                exception = GatewayError(self._extract_error_message(response))
+                exception.response = (
+                    response  # Attach response to exception for debugging
+                )
+                if raise_exceptions and exception:
+                    raise exception
+
+        return self.handle_api_response(
+            response=response,
+            request_context=payload,
+            exception=exception,
+            fatal_on_error=fatal_if_unexpected,
+            quiet=quiet,
+        )
+
+    def setup(self) -> AbstractGateway:
+        if self.default_headers is None:
+            self.default_headers = {}
+
+        return self
+
+    def _create_request_details(
+        self, request_context: HttpRequestPayload, status_code: int | None = None
+    ) -> dict[str, Any]:
+        """Create request details dictionary for logging."""
+        from wexample_helpers.helpers.cli import cli_make_clickable_path
+
+        details: dict[str, Any] = {
+            "URL": request_context.url,
+            "Method": request_context.method,
+        }
+        if request_context.call_origin:
+            details["Call Origin"] = cli_make_clickable_path(
+                request_context.call_origin
+            )
+        if request_context.data:
+            if isinstance(request_context.data, bytes):
+                details["Data"] = f"<Binary data: {len(request_context.data)} bytes>"
+            else:
+                details["Data"] = request_context.data
+        if request_context.query_params:
+            details["Query Parameters"] = request_context.query_params
+        if status_code is not None:
+            details["Status"] = status_code
+        return details
+
+    def _extract_error_message(self, response: requests.Response) -> str:
+        """Extract error message from response."""
+        message = f"HTTP {response.status_code}"
+        try:
+            data = response.json()
+            if isinstance(data, dict):
+                message = data.get("message", data.get("error", message))
+        except (ValueError, AttributeError):
+            if response.text:
+                message = response.text
+        return message
+
+    def _get_header_value(
+        self,
+        headers: Mapping[str, str] | None,
+        name: Header,
+    ) -> str | None:
+        """
+        Case-insensitive lookup of a header followed by normalisation:
+        - keep only the part before the first ';'
+        - trim whitespace
+        - convert to lower-case
+        """
+        if not headers:
+            return None
+        raw = next(
+            (v for k, v in headers.items() if k.lower() == name.value.lower()),
+            None,
+        )
+        if raw is None:
+            return None
+
+        return raw.split(";", 1)[0].strip().lower() or None
+
+    def _handle_rate_limiting(self) -> None:
+        if self.last_request_time is not None:
+            elapsed = time.time() - self.last_request_time
+            if elapsed < self.rate_limit_delay:
+                time.sleep(self.rate_limit_delay - elapsed)
+        self.last_request_time = time.time()

wexample_api-0.0.74/src/wexample_api/common/http_request_payload.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wexample_helpers.classes.base_class import BaseClass
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.decorator.base_class import base_class
+
+from wexample_api.enums.http import HttpMethod
+
+
+@base_class
+class HttpRequestPayload(BaseClass):
+    call_origin: str | None = public_field(
+        default=None,
+        description="Optional identifier of the request origin",
+    )
+    data: dict[str, Any] | bytes | None = public_field(
+        default=None,
+        description="Request body as a dictionary, raw bytes, or None",
+    )
+    expected_status_codes: list[int] | None = public_field(
+        default=None,
+        description="Optional list of expected HTTP status codes. If None, all responses are accepted.",
+    )
+    headers: dict[str, str] | None = public_field(
+        default=None,
+        description="Optional HTTP headers for the request",
+    )
+    method: HttpMethod = public_field(
+        default=HttpMethod.GET,
+        description="HTTP method to use for the request",
+    )
+    query_params: dict[str, Any] | None = public_field(
+        default=None,
+        description="Optional query parameters to append to the URL",
+    )
+    url: str = public_field(
+        description="Target URL for the HTTP request",
+    )
+
+    @classmethod
+    def from_endpoint(
+        cls,
+        base_url: str | None,
+        endpoint: str,
+        method: HttpMethod = HttpMethod.GET,
+        data: dict[str, Any] | bytes | None = None,
+        query_params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        call_origin: str | None = None,
+        expected_status_codes: int | list[int] | None = None,
+    ) -> HttpRequestPayload:
+        if base_url:
+            url = f"{base_url.rstrip('/')}/{endpoint.lstrip('/')}"
+        else:
+            url = endpoint
+
+        if isinstance(expected_status_codes, int):
+            expected_status_codes = [expected_status_codes]
+
+        return cls(
+            url=url,
+            method=method,
+            data=data,
+            query_params=query_params,
+            headers=headers,
+            call_origin=call_origin,
+            expected_status_codes=expected_status_codes,
+        )
+
+    @classmethod
+    def from_url(cls, url: str, call_origin: str | None = None) -> HttpRequestPayload:
+        return cls(url=url, call_origin=call_origin)

wexample_api-0.0.74/src/wexample_api/const/http.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from wexample_api.enums.http import HttpMethod
+
+HTTP_METHOD_MAP = {
+    "GET": HttpMethod.GET,
+    "POST": HttpMethod.POST,
+    "PUT": HttpMethod.PUT,
+    "DELETE": HttpMethod.DELETE,
+    "PATCH": HttpMethod.PATCH,
+    "OPTIONS": HttpMethod.OPTIONS,
+    "HEAD": HttpMethod.HEAD,
+}

wexample_api-0.0.74/src/wexample_api/demo/demo_simple_gateway.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wexample_helpers.decorator.base_class import base_class
+
+from wexample_api.common.abstract_gateway import AbstractGateway
+
+
+@base_class
+class DemoSimpleGateway(AbstractGateway):
+    """A simple implementation of AbstractGateway for demonstration purposes."""
+
+    def check_connection(self) -> bool:
+        # Always return True for demo purposes
+        return True
+
+    def create_item(self, item_data: dict[str, Any]) -> dict[str, Any]:
+        """Demo method to create an item."""
+        from wexample_api.enums.http import HttpMethod
+
+        response = self.make_request(
+            method=HttpMethod.POST,
+            endpoint="/items",
+            data=item_data,
+            call_origin=__file__,
+        )
+        return response.json()
+
+    def delete_item(self, item_id: str) -> None:
+        """Demo method to delete an item."""
+        from wexample_api.enums.http import HttpMethod
+
+        self.make_request(
+            method=HttpMethod.DELETE, endpoint=f"/items/{item_id}", call_origin=__file__
+        )
+
+    def get_user_info(self) -> dict[str, Any]:
+        """Demo method to get user information."""
+        from wexample_api.enums.http import HttpMethod
+
+        response = self.make_request(
+            method=HttpMethod.GET, endpoint="/user", call_origin=__file__
+        )
+        return response.json()
+
+    def update_item(self, item_id: str, item_data: dict[str, Any]) -> dict[str, Any]:
+        """Demo method to update an item."""
+        from wexample_api.enums.http import HttpMethod
+
+        response = self.make_request(
+            method=HttpMethod.PUT,
+            endpoint=f"/items/{item_id}",
+            data=item_data,
+            call_origin=__file__,
+        )
+        return response.json()

wexample_api-0.0.74/src/wexample_api/enums/http.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class HttpMethod(Enum):
+    GET: str = "GET"
+    POST: str = "POST"
+    PUT: str = "PUT"
+    DELETE: str = "DELETE"
+    PATCH: str = "PATCH"
+    OPTIONS: str = "OPTIONS"
+    HEAD: str = "HEAD"
+
+
+class ContentType(Enum):
+    JSON: str = "application/json"
+    FORM_URLENCODED: str = "application/x-www-form-urlencoded"
+    MULTIPART: str = "multipart/form-data"
+    TEXT: str = "text/plain"
+    OCTET_STREAM: str = "application/octet-stream"
+
+
+class Header(Enum):
+    CONTENT_TYPE: str = "Content-Type"
+    AUTHORIZATION: str = "Authorization"

wexample_api-0.0.74/src/wexample_api/errors/gateway_authentication_error.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from wexample_helpers.errors.gateway_error import GatewayError
+
+
+class GatewayAuthenticationError(GatewayError):
+    """Raised when authentication to the API fails."""

wexample_api-0.0.74/src/wexample_api/errors/gateway_connexion_error.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from wexample_helpers.errors.gateway_error import GatewayError
+
+
+class GatewayConnectionError(GatewayError):
+    """Raised when connection to the API fails."""

wexample_api-0.0.74/tests/common/test_http_request_payload.py

@@ -0,0 +1,108 @@
+"""Tests for HttpRequestPayload class."""
+
+from __future__ import annotations
+
+import unittest
+
+from wexample_api.enums.http import HttpMethod
+
+
+class TestHttpRequestPayload(unittest.TestCase):
+    """Test cases for HttpRequestPayload class."""
+
+    def test_direct_instantiation(self) -> None:
+        """Test direct instantiation of HttpRequestPayload."""
+        from wexample_api.common.http_request_payload import HttpRequestPayload
+
+        url = "https://api.example.com/endpoint"
+        method = HttpMethod.PUT
+        data = {"status": "active"}
+        query_params = {"version": "2"}
+        headers = {"Content-Type": "application/json"}
+
+        payload = HttpRequestPayload(
+            url=url,
+            method=method,
+            data=data,
+            query_params=query_params,
+            headers=headers,
+        )
+
+        self.assertEqual(payload.url, url)
+        self.assertEqual(payload.method, method)
+        self.assertEqual(payload.data, data)
+        self.assertEqual(payload.query_params, query_params)
+        self.assertEqual(payload.headers, headers)
+
+    def test_from_endpoint_basic(self) -> None:
+        """Test creating HttpRequestPayload from endpoint with basic parameters."""
+        from wexample_api.common.http_request_payload import HttpRequestPayload
+
+        base_url = "https://api.example.com"
+        endpoint = "/users"
+        payload = HttpRequestPayload.from_endpoint(base_url, endpoint)
+
+        self.assertEqual(payload.url, "https://api.example.com/users")
+        self.assertEqual(payload.method, HttpMethod.GET)
+        self.assertIsNone(payload.data)
+        self.assertIsNone(payload.query_params)
+        self.assertIsNone(payload.headers)
+
+    def test_from_endpoint_with_all_parameters(self) -> None:
+        """Test creating HttpRequestPayload with all optional parameters."""
+        from wexample_api.common.http_request_payload import HttpRequestPayload
+
+        base_url = "https://api.example.com"
+        endpoint = "/users"
+        method = HttpMethod.POST
+        data = {"name": "John", "age": 30}
+        query_params = {"filter": "active"}
+        headers = {"Authorization": "Bearer token"}
+
+        payload = HttpRequestPayload.from_endpoint(
+            base_url=base_url,
+            endpoint=endpoint,
+            method=method,
+            data=data,
+            query_params=query_params,
+            headers=headers,
+        )
+
+        self.assertEqual(payload.url, "https://api.example.com/users")
+        self.assertEqual(payload.method, HttpMethod.POST)
+        self.assertEqual(payload.data, data)
+        self.assertEqual(payload.query_params, query_params)
+        self.assertEqual(payload.headers, headers)
+
+    def test_from_endpoint_with_trailing_slash(self) -> None:
+        """Test creating HttpRequestPayload with trailing slash in base_url."""
+        from wexample_api.common.http_request_payload import HttpRequestPayload
+
+        base_url = "https://api.example.com/"
+        endpoint = "/users"
+        payload = HttpRequestPayload.from_endpoint(base_url, endpoint)
+
+        self.assertEqual(payload.url, "https://api.example.com/users")
+
+    def test_from_endpoint_without_leading_slash(self) -> None:
+        """Test creating HttpRequestPayload without leading slash in endpoint."""
+        from wexample_api.common.http_request_payload import HttpRequestPayload
+
+        base_url = "https://api.example.com"
+        endpoint = "users"
+        payload = HttpRequestPayload.from_endpoint(base_url, endpoint)
+
+        self.assertEqual(payload.url, "https://api.example.com/users")
+
+    def test_from_url(self) -> None:
+        """Test creating HttpRequestPayload from URL."""
+        from wexample_api.common.http_request_payload import HttpRequestPayload
+
+        url = "https://api.example.com/endpoint"
+        payload = HttpRequestPayload.from_url(url)
+
+        self.assertEqual(payload.url, url)
+        self.assertEqual(payload.method, HttpMethod.GET)
+        self.assertIsNone(payload.data)
+        self.assertIsNone(payload.query_params)
+        self.assertIsNone(payload.headers)

wexample_api-0.0.74/tests/demo/test_demo_simple_gateway.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from unittest.mock import patch
+
+import pytest
+
+if TYPE_CHECKING:
+    from unittest.mock import MagicMock
+
+    from wexample_prompt.common.io_manager import IoManager
+
+    from wexample_api.demo.demo_simple_gateway import DemoSimpleGateway
+
+
+def create_mock_response(status_code=200, json_data=None) -> MagicMock:
+    from unittest.mock import MagicMock
+
+    from requests import Response
+
+    mock_response = MagicMock(spec=Response)
+    mock_response.status_code = status_code
+    mock_response.json.return_value = json_data or {}
+    return mock_response
+
+
+@pytest.fixture
+def gateway(io_manager) -> DemoSimpleGateway:
+    from wexample_api.demo.demo_simple_gateway import DemoSimpleGateway
+
+    return DemoSimpleGateway(base_url="https://api.example.com", io=io_manager)
+
+
+@pytest.fixture
+def io_manager() -> IoManager:
+    from wexample_prompt.common.io_manager import IoManager
+
+    return IoManager()
+
+
+def test_check_connection(gateway) -> None:
+    assert gateway.check_connection() is True
+
+
+@patch("requests.request")
+def test_create_item(mock_request, gateway) -> None:
+    # Arrange
+    item_data = {"name": "Test Item"}
+    expected_response = {"id": 1, **item_data}
+    mock_request.return_value = create_mock_response(json_data=expected_response)
+    gateway.connected = True
+
+    # Act
+    result = gateway.create_item(item_data)
+
+    # Assert
+    assert result == expected_response
+    mock_request.assert_called_once_with(
+        method="POST",
+        url="https://api.example.com/items",
+        json=item_data,
+        params=None,
+        headers={},
+        timeout=30,
+        stream=False,
+    )
+
+
+@patch("requests.request")
+def test_delete_item(mock_request, gateway) -> None:
+    # Arrange
+    item_id = "123"
+    mock_request.return_value = create_mock_response()
+    gateway.connected = True
+
+    # Act
+    gateway.delete_item(item_id)
+
+    # Assert
+    mock_request.assert_called_once_with(
+        method="DELETE",
+        url=f"https://api.example.com/items/{item_id}",
+        json=None,
+        params=None,
+        headers={},
+        timeout=30,
+        stream=False,
+    )
+
+
+@patch("requests.request")
+def test_get_user_info(mock_request, gateway) -> None:
+    # Arrange
+    expected_data = {"id": 1, "name": "Test User"}
+    mock_request.return_value = create_mock_response(json_data=expected_data)
+    gateway.connected = True
+
+    # Act
+    result = gateway.get_user_info()
+
+    # Assert
+    assert result == expected_data
+    mock_request.assert_called_once_with(
+        method="GET",
+        url="https://api.example.com/user",
+        json=None,
+        params=None,
+        headers={},
+        timeout=30,
+        stream=False,
+    )
+
+
+def test_not_connected_error(gateway) -> None:
+    # Arrange
+    gateway.connected = False
+
+    # Act & Assert
+    with pytest.raises(AttributeError):
+        gateway.get_user_info()
+
+
+@patch("requests.request")
+def test_update_item(mock_request, gateway) -> None:
+    # Arrange
+    item_id = "123"
+    item_data = {"name": "Updated Item"}
+    expected_response = {"id": item_id, **item_data}
+    mock_request.return_value = create_mock_response(json_data=expected_response)
+    gateway.connected = True
+
+    # Act
+    result = gateway.update_item(item_id, item_data)
+
+    # Assert
+    assert result == expected_response
+    mock_request.assert_called_once_with(
+        method="PUT",
+        url=f"https://api.example.com/items/{item_id}",
+        json=item_data,
+        params=None,
+        headers={},
+        timeout=30,
+        stream=False,
+    )