xwapi 0.9.0.2__tar.gz

xwapi-0.9.0.2/.github/workflows/check-versions.yml

@@ -0,0 +1,31 @@
+## NOTE: AUTO-GENERATED FILE
+## This workflow was generated by tools/ci/python_scripts/generate_workflows.py.
+## Do NOT edit this file manually - changes will be overwritten.
+
+name: Check for Hardcoded Versions
+
+on:
+  pull_request:
+    paths:
+      - 'src/**/*.py'
+      - 'tests/**/*.py'
+      - 'docs/**/*.md'
+      - '*.md'
+      - '*.txt'
+  push:
+    branches: [main, develop]
+
+jobs:
+  check-versions:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+
+      - name: Verify version.py is the source of truth
+        run: |
+          python .github/workflows/check_version_source_of_truth.py

xwapi-0.9.0.2/.github/workflows/check_version_source_of_truth.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""
+Verify that the version configured in pyproject.toml ultimately comes from a
+single source-of-truth version location (file or attribute) and print it.
+
+This is extracted from the GitHub Actions check-versions workflow so it can be
+tested and reused outside of CI.
+"""
+
+from __future__ import annotations
+
+import importlib
+import re
+import sys
+from pathlib import Path
+
+
+def _read_pyproject() -> str:
+    path = Path("pyproject.toml")
+    if not path.exists():
+        print("No pyproject.toml", file=sys.stderr)
+        sys.exit(2)
+    return path.read_text(encoding="utf-8")
+
+
+def _read_attr_from_module_source(
+    project_root: Path,
+    module_name: str,
+    attr_name: str,
+) -> str | None:
+    """
+    Resolve module source under ./src and read a simple string assignment
+    like: __version__ = "1.2.3"
+    This avoids import side effects from package-level dependencies.
+    """
+    module_rel = Path(*module_name.split("."))
+    candidates = [
+        project_root / "src" / (str(module_rel) + ".py"),
+        project_root / "src" / module_rel / "__init__.py",
+    ]
+    pattern = re.compile(
+        rf"^\s*{re.escape(attr_name)}\s*=\s*['\"]([^'\"]+)['\"]\s*$",
+        re.MULTILINE,
+    )
+    for candidate in candidates:
+        if not candidate.exists():
+            continue
+        text = candidate.read_text(encoding="utf-8")
+        m = pattern.search(text)
+        if m:
+            return m.group(1)
+    return None
+
+
+def main() -> None:
+    text = _read_pyproject()
+
+    # 1) Hatchling: [tool.hatch.version] path = ".../version.py"
+    m = re.search(
+        r"\[tool\.hatch\.version\][^\n]*\n\s*path\s*=\s*[\"']([^\"']+)[\"']",
+        text,
+        re.DOTALL,
+    )
+    if m:
+        version_file = Path(m.group(1).strip())
+        if not version_file.exists():
+            print(f"Version file not found: {version_file}", file=sys.stderr)
+            sys.exit(2)
+        ns: dict[str, object] = {}
+        exec(version_file.read_text(encoding="utf-8"), ns)
+        version = ns.get("__version__")
+        if not isinstance(version, str) or not version:
+            print(f"__version__ missing or empty in {version_file}", file=sys.stderr)
+            sys.exit(2)
+        print("Current version:", version)
+        sys.exit(0)
+
+    # 2) Setuptools dynamic inline table (file=...) -> open version file and exec
+    m = re.search(
+        r'version\s*=\s*\{\s*file\s*=\s*["\']([^"\']+)["\']',
+        text,
+        re.DOTALL,
+    )
+    if not m:
+        # 2b) Setuptools dynamic table style:
+        # [tool.setuptools.dynamic.version]
+        # attr = "pkg.module.__version__" OR file = "..."
+        m = re.search(
+            r"\[tool\.setuptools\.dynamic\.version\][^\n]*\n\s*file\s*=\s*[\"']([^\"']+)[\"']",
+            text,
+            re.DOTALL,
+        )
+    if m:
+        version_file = Path(m.group(1).strip())
+        if not version_file.exists():
+            print(f"Version file not found: {version_file}", file=sys.stderr)
+            sys.exit(2)
+        ns: dict[str, object] = {}
+        exec(version_file.read_text(encoding="utf-8"), ns)
+        version = ns.get("__version__")
+        if not isinstance(version, str) or not version:
+            print(f"__version__ missing or empty in {version_file}", file=sys.stderr)
+            sys.exit(2)
+        print("Current version:", version)
+        sys.exit(0)
+
+    # 3) Setuptools dynamic inline table (attr="pkg.module.__version__")
+    m = re.search(
+        r'version\s*=\s*\{\s*attr\s*=\s*["\']([^"\']+)["\']',
+        text,
+        re.DOTALL,
+    )
+    if not m:
+        # 3b) Setuptools dynamic table style:
+        # [tool.setuptools.dynamic.version]
+        # attr = "pkg.module.__version__"
+        m = re.search(
+            r"\[tool\.setuptools\.dynamic\.version\][^\n]*\n\s*attr\s*=\s*[\"']([^\"']+)[\"']",
+            text,
+            re.DOTALL,
+        )
+    if m:
+        attr_path = m.group(1).strip()
+        module_name, _, attr = attr_path.rpartition(".")
+        if not module_name or not attr:
+            sys.exit(2)
+        version = _read_attr_from_module_source(Path("."), module_name, attr)
+        if version is None:
+            # Fallback to import for unusual dynamic cases.
+            mod = importlib.import_module(module_name)
+            version = getattr(mod, attr, None)
+        if not isinstance(version, str) or not version:
+            print(
+                f"Attribute {attr_path} is missing or empty",
+                file=sys.stderr,
+            )
+            sys.exit(2)
+        print("Current version:", version)
+        sys.exit(0)
+
+    # If none of the patterns matched, exit with a non-success status expected by CI.
+    sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()
+

xwapi-0.9.0.2/.github/workflows/compliance.yml

@@ -0,0 +1,38 @@
+name: xwapi Compliance
+
+on:
+  pull_request:
+    paths:
+      - "xwapi/**"
+      - "tools/ci/python_scripts/**"
+  push:
+    branches: ["main"]
+    paths:
+      - "xwapi/**"
+      - "tools/ci/python_scripts/**"
+
+jobs:
+  compliance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r xwapi/requirements.txt
+
+      - name: Format & type checks
+        run: |
+          black --check xwapi/src xwapi/tests
+          isort --check-only xwapi/src xwapi/tests
+          mypy xwapi/src
+
+      - name: Test suite
+        run: |
+          python -m pytest xwapi/tests

xwapi-0.9.0.2/.github/workflows/publish.yml

@@ -0,0 +1,70 @@
+# NOTE: AUTO-GENERATED FILE
+# This workflow was generated by tools/ci/python_scripts/generate_workflows.py.
+# Do NOT edit this file manually - changes will be overwritten.
+
+name: Dual PyPI Publish - exonware-xwapi & xwapi
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches version.py
+        run: |
+          python .github/workflows/verify_tag_matches_version.py
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Set release date to today
+        run: |
+          python .github/workflows/update_release_date_from_version_file.py
+
+      - name: Build exonware-xwapi package
+        run: |
+          echo "Building exonware-xwapi package..."
+          python -m build
+
+      - name: Build xwapi package
+        run: |
+          echo "Building xwapi package..."
+          cp pyproject.toml pyproject.backup.toml
+          cp pyproject.xwapi.toml pyproject.toml
+          python -m build
+          mv pyproject.backup.toml pyproject.toml
+
+      - name: List built packages
+        run: |
+          echo "Built packages:"
+          find dist -name "*.whl" -o -name "*.tar.gz" | sort
+
+      - name: Publish exonware-xwapi to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          echo "Publishing exonware-xwapi to PyPI..."
+          twine upload dist/exonware_xwapi-*.whl dist/exonware_xwapi-*.tar.gz
+
+      - name: Publish xwapi to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          echo "Publishing xwapi to PyPI..."
+          twine upload dist/xwapi-*.whl dist/xwapi-*.tar.gz

xwapi-0.9.0.2/.github/workflows/update_release_date_from_version_file.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""
+Update a __date__ literal in the version file referenced from pyproject.toml
+to today's ISO date (YYYY-MM-DD), when present as a string literal.
+
+This is extracted from the GitHub Actions publish workflow so it can be reused
+and tested outside of CI.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from datetime import date
+from pathlib import Path
+
+
+def main() -> None:
+    pyproject_path = Path("pyproject.toml")
+    if not pyproject_path.exists():
+        print("No pyproject.toml; skipping __date__ update")
+        sys.exit(0)
+
+    pyproject = pyproject_path.read_text(encoding="utf-8")
+    m = re.search(
+        r"\[tool\.hatch\.version\][^\n]*\n\s*path\s*=\s*[\"']([^\"']+)[\"']",
+        pyproject,
+        re.DOTALL,
+    )
+    if not m:
+        print("No [tool.hatch.version] path; skipping __date__ update")
+        sys.exit(0)
+
+    version_file = Path(m.group(1).strip())
+    if not version_file.exists():
+        print(f"Version file not found: {version_file}; skipping __date__ update")
+        sys.exit(0)
+
+    text = version_file.read_text(encoding="utf-8")
+    literal_match = re.search(
+        r"__date__\s*=\s*[\"'][^\"']*[\"']",
+        text,
+    )
+    if not literal_match:
+        print("__date__ is dynamic or missing; no update needed")
+        sys.exit(0)
+
+    today = date.today().isoformat()
+    new_text = re.sub(
+        r"(__date__\s*=\s*)[\"'][^\"']*[\"']",
+        r'\1"' + today + '"',
+        text,
+    )
+    version_file.write_text(new_text, encoding="utf-8")
+    print("Set __date__ to", today, "in", version_file)
+
+
+if __name__ == "__main__":
+    main()
+

xwapi-0.9.0.2/.github/workflows/verify_tag_matches_version.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""
+Verify that the current Git reference (tag) matches the library version defined
+in the version file referenced from pyproject.toml.
+
+This script is extracted from the GitHub Actions publish workflow so it can be
+reused and tested outside of CI.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from pathlib import Path
+
+
+def _load_version_from_pyproject() -> str | None:
+    pyproject_path = Path("pyproject.toml")
+    if not pyproject_path.exists():
+        print("No pyproject.toml; skipping", file=sys.stderr)
+        return None
+
+    text = pyproject_path.read_text(encoding="utf-8")
+    m = re.search(
+        r"\[tool\.hatch\.version\][^\n]*\n\s*path\s*=\s*[\"']([^\"']+)[\"']",
+        text,
+        re.DOTALL,
+    )
+    if not m:
+        print("No [tool.hatch.version] path; skipping", file=sys.stderr)
+        return None
+
+    version_file = Path(m.group(1).strip())
+    if not version_file.exists():
+        print(f"Version file not found: {version_file}", file=sys.stderr)
+        sys.exit(1)
+
+    ns: dict[str, object] = {}
+    exec(version_file.read_text(encoding="utf-8"), ns)
+    version = ns.get("__version__")
+    if not isinstance(version, str) or not version:
+        print(f"__version__ missing or empty in {version_file}", file=sys.stderr)
+        sys.exit(1)
+    return version
+
+
+def main() -> None:
+    file_ver = _load_version_from_pyproject()
+    if not file_ver:
+        sys.exit(0)
+
+    ref = os.environ.get("GITHUB_REF", "")
+    if not ref.startswith("refs/tags/"):
+        print(f"Not a tag build; version: {file_ver}")
+        sys.exit(0)
+
+    tag_name = ref.removeprefix("refs/tags/")
+    tag_ver = tag_name[1:] if tag_name.startswith("v") else tag_name
+
+    if tag_ver != file_ver:
+        print(f"ERROR: Tag {tag_ver} != version.py {file_ver}", file=sys.stderr)
+        sys.exit(1)
+
+    print("OK: tag and version match:", file_ver)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

xwapi-0.9.0.2/.github/workflows-config.yaml

@@ -0,0 +1,8 @@
+projects:
+  xwapi:
+    repo: xwapi
+    package_main: exonware-xwapi
+    package_wrapper: xwapi
+    python_version: "3.12"
+    has_wrapper: true
+    uses_check_versions: true

xwapi-0.9.0.2/.gitignore

@@ -0,0 +1,66 @@
+# 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
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Documentation
+docs/_build/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# xwlazy generated files (should be in ~/.xwlazy/ but ignore in case of old behavior)
+xwlazy.lock.toml
+xwlazy_sbom.toml
+
+# Local archive folders
+.archieve/
+
+# Local secrets file
+.secrets
+
+.examples/
+
+# Local private folders
+.secrets
+.references
+.venv
+.archive
+

xwapi-0.9.0.2/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 eXonware.com - eXonware Backend Team
+
+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.
+

xwapi-0.9.0.2/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: xwapi
+Version: 0.9.0.2
+Summary: Convenience wrapper for exonware-xwapi - provides 'import xwapi' alias
+Project-URL: Homepage, https://exonware.com
+Project-URL: Repository, https://github.com/exonware/xwapi
+Project-URL: Documentation, https://github.com/exonware/xwapi#readme
+Project-URL: Subtree, https://github.com/exonware/xwapi.git
+Author-email: eXonware Backend Team <connect@exonware.com>
+License: MIT
+License-File: LICENSE
+Keywords: api,exonware,fastapi,graphql,oauth2,openapi,rest
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: exonware-xwapi
+Provides-Extra: dev
+Requires-Dist: exonware-xwapi[dev]; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: exonware-xwapi[full]; extra == 'full'
+Provides-Extra: lazy
+Requires-Dist: exonware-xwapi[lazy]; extra == 'lazy'
+Provides-Extra: storage
+Requires-Dist: exonware-xwapi[storage]; extra == 'storage'
+Description-Content-Type: text/markdown
+
+# xwapi
+
+Engine-agnostic API framework for the eXonware stack. `xwapi` exposes `xwentity` and `xwaction` as HTTP endpoints, standardizes error contracts, supports production middleware, and now includes a durable action pipeline plus API token lifecycle/metering.
+
+*Longer guide: [README_LONG.md](README_LONG.md).*
+
+**Company:** eXonware.com · **Author:** eXonware Backend Team · **Email:** connect@exonware.com
+
+[![Status](https://img.shields.io/badge/status-beta-blue.svg)](https://exonware.com)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+---
+
+## Install
+
+| Install | When to use |
+|---------|-------------|
+| `pip install exonware-xwapi` | Core runtime |
+| `pip install exonware-xwapi[lazy]` | Lazy dependency loading |
+| `pip install exonware-xwapi[full]` | Full production dependency set |
+
+---
+
+## Quick start
+
+```python
+from exonware.xwapi import XWAPI
+from exonware.xwentity import XWEntity
+
+
+class User(XWEntity):
+    name: str
+    email: str
+    age: int
+
+
+api = XWAPI(entities=[User], title="My API", version="1.0.0")
+app = api.create_app(engine="fastapi")
+```
+
+---
+
+## New production features
+
+- **Engine-agnostic error contract:** `xwapi_error_to_http_parts` plus adapters keeps `XWAPIError` transport-neutral.
+- **Outbox + singleton worker pipeline:** `ActionPipelineManager`, `AOutboxStore`/`InMemoryOutboxStore`, and `BackgroundWorker`.
+- **API token lifecycle:** create/list/revoke tokens, usage tracking, balance/recharge, idempotent metering.
+- **Provider abstractions:** `IAuthProvider`, `IStorageProvider`, `IPaymentProvider` with in-memory and library adapters.
+- **API token middleware:** bearer verification, optional scope enforcement, deny-unmapped policy, usage metering via `Idempotency-Key`.
+- **Admin/operations endpoints:** server status/health/pipeline controls and token admin endpoints.
+- **Production guardrails:** environment-based admin token enforcement and admin read-protection support.
+
+---
+
+## eXonware integration
+
+`xwapi` now explicitly integrates with:
+
+- `xwsystem` (serialization, logging/utilities)
+- `xwaction` (action registration and execution)
+- `xwentity` (entity-driven API surfaces)
+- `xwschema` (schema validation/generation integration points)
+- `xwdata` (data/serialization integration paths)
+
+---
+
+## Docs and tests
+
+- Start at [docs/INDEX.md](docs/INDEX.md).
+- API and architecture references: [docs/REF_15_API.md](docs/REF_15_API.md), [docs/REF_13_ARCH.md](docs/REF_13_ARCH.md).
+- Test layers: `0.core`, `1.unit`, `2.integration`, `3.advance`.
+- Full run: `python tests/runner.py`
+
+---
+
+## Async support
+
+- Core runtime includes async methods across facade, token manager, middleware paths, and server actions.
+- Async APIs are recommended for I/O-heavy and concurrent workloads.
+
+---
+
+MIT - see [LICENSE](LICENSE). Homepage: https://exonware.com
+Version: 0.9.0.2 | Updated: 01-Apr-2026
+
+*Built with ❤️ by eXonware.com - Revolutionizing Python Development Since 2025*