finalsa-common-http-client 0.0.1__tar.gz

finalsa_common_http_client-0.0.1/.gitignore

@@ -0,0 +1,117 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+test.db
+
+.DS_Store

finalsa_common_http_client-0.0.1/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Luis Diego Jiménez Delgado
+
+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.

finalsa_common_http_client-0.0.1/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: finalsa-common-http-client
+Version: 0.0.1
+Summary: HTTP client library for common data types used in business applications
+Project-URL: Homepage, https://github.com/finalsa/finalsa-http-client
+Project-URL: Documentation, https://github.com/finalsa/finalsa-http-client#readme
+Project-URL: Repository, https://github.com/finalsa/finalsa-http-client.git
+Project-URL: Issues, https://github.com/finalsa/finalsa-http-client/issues
+Project-URL: Changelog, https://github.com/finalsa/finalsa-http-client/blob/main/CHANGELOG.md
+Author-email: Luis Jimenez <luis@finalsa.com>
+License: MIT License
+        
+        Copyright (c) 2021 Luis Diego Jiménez Delgado
+        
+        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.
+License-File: LICENSE.md
+Keywords: client,finalsa,http
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Internationalization
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Localization
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: aiohttp>=3.10.5
+Requires-Dist: fastapi>=0.116.1
+Requires-Dist: finalsa-traceability>=1.0.1
+Requires-Dist: requests>=2.32.4
+Description-Content-Type: text/markdown
+
+# Finalsa HTTP Client
+
+`finalsa-http-client` provides small, well-tested base classes for building HTTP
+clients that share a consistent set of defaults across Finalsa services. One
+implementation wraps `requests` for synchronous workloads and the other wraps
+`aiohttp` for asyncio-aware code.
+
+- Normalizes `base_url` values and fills in schemes automatically.
+- Builds a predictable `User-Agent` header (e.g. `finalsa-http-client/0.0.1`).
+- Merges per-request headers with service defaults.
+- Manages the underlying session lifecycle (context manager friendly).
+- Lets you opt into strict `raise_for_status` behavior on every request.
+
+## Installation
+
+```bash
+python -m pip install finalsa-http-client
+```
+
+## Synchronous usage
+
+```python
+from finalsa.http.sync import BaseSyncHttpClient
+
+with BaseSyncHttpClient(
+    base_url="https://api.example.test",
+    service_name="billing-api",
+    default_headers={"X-App": "billing"},
+    timeout=5,  # seconds
+    trust_env=False,
+) as client:
+    response = client.post(
+        "/v1/invoices",
+        json={"customer_id": "cust_123", "total": 1999},
+        params={"dry_run": False},
+    )
+    print(response.json())
+```
+
+Key synchronous notes:
+
+- `base_url` can be provided without a scheme (`api.example.test`), the client
+  will inject the configured `default_scheme` (defaults to `http`).
+- Use `.build_url()` when you need the normalized URL without sending a request.
+- `service_name` is used to stamp the `User-Agent`. You can still call
+  `.update_default_headers()` later if you need to augment the defaults.
+- Set `trust_env=False` (default is `True`) to keep the underlying `requests`
+  session from honoring proxy-related environment variables.
+- Pass `url="https://status.example.test/health"` to `.request()` to bypass the
+  configured `base_url`.
+
+## Asynchronous usage
+
+```python
+import asyncio
+
+from finalsa.http.async import BaseAsyncHttpClient
+
+
+async def main() -> None:
+    async with BaseAsyncHttpClient(
+        base_url="https://api.example.test",
+        service_name="billing-api",
+        trust_env=True,  # honor proxy-related env vars
+        timeout=10,
+    ) as client:
+        response = await client.get("/v1/health", params={"extended": True})
+        payload = await response.json()
+        print(payload)
+
+
+asyncio.run(main())
+```
+
+Asynchronous specifics:
+
+- Timeouts accept either a float (seconds) or an explicit `aiohttp.ClientTimeout`.
+- `service_name` mirrors the sync client parameter and controls the leading
+  portion of the `User-Agent` header.
+- `trust_env=True` allows `aiohttp` to reuse proxy / SSL options from the host
+  environment.
+- You can supply an existing `aiohttp.ClientSession` via the `session` keyword
+  when you want to keep full control over connection pooling. The client will
+  detect that it does not own the session and skip closing it.
+
+## URL handling & headers
+
+- Both clients share helpers in `finalsa.http._shared` for URL resolution,
+  header merging, and scheme enforcement.
+- Per-request headers passed to `.request()` (or `.get()`, `.post()`, etc.) are
+  merged on top of the client's defaults without mutating the stored defaults.
+- When neither `path` nor `url` is provided, `.request()` raises `ValueError` to
+  surface misconfigurations early.
+
+## Sessions, timeouts & errors
+
+- Entering the client as a context manager ensures the underlying session is
+  created once and cleaned up automatically. You can also call `.close()` when
+  managing the lifecycle manually.
+- `BaseSyncHttpClient` defaults to `raise_for_status=True` and will immediately
+  raise any non-2xx response. The async variant passes the same flag through to
+  `aiohttp.ClientSession`.
+- Supplying your own session (`requests.Session` or `aiohttp.ClientSession`)
+  allows you to plug in custom retry adapters, authentication, or tracing
+  middleware while still benefiting from URL building and header management.
+
+## Migrating from `@responses.activate`
+
+Many of our legacy tests used the `responses` package to stub outgoing HTTP
+traffic. You can keep the same ergonomics with `BaseSyncHttpClient` and adopt a
+similar pattern for asyncio-based code.
+
+### Sync tests (requests + responses)
+
+```python
+import responses
+from finalsa.http.sync import BaseSyncHttpClient
+
+
+@responses.activate
+def test_creates_invoice() -> None:
+    responses.add(
+        method=responses.POST,
+        url="https://api.example.test/v1/invoices",
+        json={"id": "inv_123", "status": "draft"},
+        status=201,
+    )
+
+    client = BaseSyncHttpClient(base_url="https://api.example.test")
+
+    response = client.post("/v1/invoices", json={"total": 5000})
+
+    assert response.json()["status"] == "draft"
+    assert len(responses.calls) == 1
+```
+
+Nothing special is required: because the client reuses `requests.Session`, any
+`responses.activate` or `responses.RequestsMock` context automatically captures
+the outgoing call.
+
+### Async tests (aiohttp + aioresponses)
+
+Use [`aioresponses`](https://github.com/pnuckowski/aioresponses) (or your async
+HTTP mock of choice) to intercept `aiohttp` traffic:
+
+```python
+import pytest
+from aioresponses import aioresponses
+from finalsa.http.async import BaseAsyncHttpClient
+
+
+@pytest.mark.asyncio
+async def test_health_check() -> None:
+    client = BaseAsyncHttpClient(base_url="https://api.example.test")
+
+    with aioresponses() as mocked:
+        mocked.get(
+            "https://api.example.test/v1/health",
+            payload={"status": "ok"},
+            status=200,
+        )
+
+        response = await client.get("/v1/health")
+        assert await response.json() == {"status": "ok"}
+        assert ("GET", "https://api.example.test/v1/health") in mocked.requests
+```
+
+Behind the scenes the async client creates an `aiohttp.ClientSession`, so tools
+like `aioresponses`, `aresponses`, or `pytest-aiohttp` slot in naturally. For
+more brittle tests you can also inject your own `ClientSession` (e.g. one backed
+by a stub transport) through the `session` constructor argument.
+
+## Development
+
+```bash
+python -m pip install -e ".[test]"
+pytest
+```
+
+The test suite demonstrates additional patterns (custom timeouts, header
+merging, session injection) if you need more examples. Feel free to open an
+issue or pull request on GitHub with improvements or questions.

finalsa_common_http_client-0.0.1/README.md

@@ -0,0 +1,182 @@
+# Finalsa HTTP Client
+
+`finalsa-http-client` provides small, well-tested base classes for building HTTP
+clients that share a consistent set of defaults across Finalsa services. One
+implementation wraps `requests` for synchronous workloads and the other wraps
+`aiohttp` for asyncio-aware code.
+
+- Normalizes `base_url` values and fills in schemes automatically.
+- Builds a predictable `User-Agent` header (e.g. `finalsa-http-client/0.0.1`).
+- Merges per-request headers with service defaults.
+- Manages the underlying session lifecycle (context manager friendly).
+- Lets you opt into strict `raise_for_status` behavior on every request.
+
+## Installation
+
+```bash
+python -m pip install finalsa-http-client
+```
+
+## Synchronous usage
+
+```python
+from finalsa.http.sync import BaseSyncHttpClient
+
+with BaseSyncHttpClient(
+    base_url="https://api.example.test",
+    service_name="billing-api",
+    default_headers={"X-App": "billing"},
+    timeout=5,  # seconds
+    trust_env=False,
+) as client:
+    response = client.post(
+        "/v1/invoices",
+        json={"customer_id": "cust_123", "total": 1999},
+        params={"dry_run": False},
+    )
+    print(response.json())
+```
+
+Key synchronous notes:
+
+- `base_url` can be provided without a scheme (`api.example.test`), the client
+  will inject the configured `default_scheme` (defaults to `http`).
+- Use `.build_url()` when you need the normalized URL without sending a request.
+- `service_name` is used to stamp the `User-Agent`. You can still call
+  `.update_default_headers()` later if you need to augment the defaults.
+- Set `trust_env=False` (default is `True`) to keep the underlying `requests`
+  session from honoring proxy-related environment variables.
+- Pass `url="https://status.example.test/health"` to `.request()` to bypass the
+  configured `base_url`.
+
+## Asynchronous usage
+
+```python
+import asyncio
+
+from finalsa.http.async import BaseAsyncHttpClient
+
+
+async def main() -> None:
+    async with BaseAsyncHttpClient(
+        base_url="https://api.example.test",
+        service_name="billing-api",
+        trust_env=True,  # honor proxy-related env vars
+        timeout=10,
+    ) as client:
+        response = await client.get("/v1/health", params={"extended": True})
+        payload = await response.json()
+        print(payload)
+
+
+asyncio.run(main())
+```
+
+Asynchronous specifics:
+
+- Timeouts accept either a float (seconds) or an explicit `aiohttp.ClientTimeout`.
+- `service_name` mirrors the sync client parameter and controls the leading
+  portion of the `User-Agent` header.
+- `trust_env=True` allows `aiohttp` to reuse proxy / SSL options from the host
+  environment.
+- You can supply an existing `aiohttp.ClientSession` via the `session` keyword
+  when you want to keep full control over connection pooling. The client will
+  detect that it does not own the session and skip closing it.
+
+## URL handling & headers
+
+- Both clients share helpers in `finalsa.http._shared` for URL resolution,
+  header merging, and scheme enforcement.
+- Per-request headers passed to `.request()` (or `.get()`, `.post()`, etc.) are
+  merged on top of the client's defaults without mutating the stored defaults.
+- When neither `path` nor `url` is provided, `.request()` raises `ValueError` to
+  surface misconfigurations early.
+
+## Sessions, timeouts & errors
+
+- Entering the client as a context manager ensures the underlying session is
+  created once and cleaned up automatically. You can also call `.close()` when
+  managing the lifecycle manually.
+- `BaseSyncHttpClient` defaults to `raise_for_status=True` and will immediately
+  raise any non-2xx response. The async variant passes the same flag through to
+  `aiohttp.ClientSession`.
+- Supplying your own session (`requests.Session` or `aiohttp.ClientSession`)
+  allows you to plug in custom retry adapters, authentication, or tracing
+  middleware while still benefiting from URL building and header management.
+
+## Migrating from `@responses.activate`
+
+Many of our legacy tests used the `responses` package to stub outgoing HTTP
+traffic. You can keep the same ergonomics with `BaseSyncHttpClient` and adopt a
+similar pattern for asyncio-based code.
+
+### Sync tests (requests + responses)
+
+```python
+import responses
+from finalsa.http.sync import BaseSyncHttpClient
+
+
+@responses.activate
+def test_creates_invoice() -> None:
+    responses.add(
+        method=responses.POST,
+        url="https://api.example.test/v1/invoices",
+        json={"id": "inv_123", "status": "draft"},
+        status=201,
+    )
+
+    client = BaseSyncHttpClient(base_url="https://api.example.test")
+
+    response = client.post("/v1/invoices", json={"total": 5000})
+
+    assert response.json()["status"] == "draft"
+    assert len(responses.calls) == 1
+```
+
+Nothing special is required: because the client reuses `requests.Session`, any
+`responses.activate` or `responses.RequestsMock` context automatically captures
+the outgoing call.
+
+### Async tests (aiohttp + aioresponses)
+
+Use [`aioresponses`](https://github.com/pnuckowski/aioresponses) (or your async
+HTTP mock of choice) to intercept `aiohttp` traffic:
+
+```python
+import pytest
+from aioresponses import aioresponses
+from finalsa.http.async import BaseAsyncHttpClient
+
+
+@pytest.mark.asyncio
+async def test_health_check() -> None:
+    client = BaseAsyncHttpClient(base_url="https://api.example.test")
+
+    with aioresponses() as mocked:
+        mocked.get(
+            "https://api.example.test/v1/health",
+            payload={"status": "ok"},
+            status=200,
+        )
+
+        response = await client.get("/v1/health")
+        assert await response.json() == {"status": "ok"}
+        assert ("GET", "https://api.example.test/v1/health") in mocked.requests
+```
+
+Behind the scenes the async client creates an `aiohttp.ClientSession`, so tools
+like `aioresponses`, `aresponses`, or `pytest-aiohttp` slot in naturally. For
+more brittle tests you can also inject your own `ClientSession` (e.g. one backed
+by a stub transport) through the `session` constructor argument.
+
+## Development
+
+```bash
+python -m pip install -e ".[test]"
+pytest
+```
+
+The test suite demonstrates additional patterns (custom timeouts, header
+merging, session injection) if you need more examples. Feel free to open an
+issue or pull request on GitHub with improvements or questions.

finalsa_common_http_client-0.0.1/finalsa/http/_shared.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from importlib import metadata
+from urllib.parse import urljoin
+
+from finalsa.traceability import get_w3c_traceparent, get_w3c_tracestate
+from finalsa.traceability.functions import (
+    HTTP_HEADER_TRACEPARENT,
+    HTTP_HEADER_TRACESTATE,
+)
+
+Headers = Mapping[str, str]
+
+
+def normalize_base_url(
+    base_url: str | None,
+    default_scheme: str,
+) -> str | None:
+    """Return a normalized base URL or None when no usable value is provided."""
+    if not base_url:
+        return None
+    value = base_url.strip()
+    if not value:
+        return None
+    if "://" not in value:
+        value = f"{default_scheme}://{value}"
+    return value.rstrip("/")
+
+
+def ensure_scheme(candidate: str, default_scheme: str) -> str:
+    """Ensure that the provided candidate has an explicit scheme."""
+    trimmed = candidate.strip()
+    if "://" in trimmed:
+        return trimmed
+    return f"{default_scheme}://{trimmed}"
+
+
+def build_url(
+    *,
+    path: str | None,
+    url: str | None,
+    base_url: str | None,
+    default_scheme: str,
+) -> str:
+    """Resolve the final request URL from the supplied inputs."""
+    if url:
+        return ensure_scheme(url, default_scheme)
+
+    if path is None:
+        raise ValueError("Either 'path' or 'url' must be provided.")
+
+    candidate = path.strip()
+    if candidate.startswith(("http://", "https://")):
+        return candidate
+    if base_url:
+        base = base_url if base_url.endswith("/") else f"{base_url}/"
+        return urljoin(base, candidate.lstrip("/"))
+    return ensure_scheme(candidate, default_scheme)
+
+
+def merge_headers(
+    default_headers: Mapping[str, str],
+    headers: Mapping[str, str] | None,
+) -> dict[str, str]:
+    """Merge default headers with any per-request overrides."""
+    merged = dict(default_headers)
+    if headers:
+        merged.update(headers)
+    merged[HTTP_HEADER_TRACEPARENT] = get_w3c_traceparent()
+    merged[HTTP_HEADER_TRACESTATE] = get_w3c_tracestate()
+    return merged
+
+
+def build_default_headers(
+    default_headers: Mapping[str, str],
+    user_headers: Mapping[str, str] | None,
+    service_name: str,
+) -> dict[str, str]:
+    """Construct the default header set for an HTTP client."""
+    headers = dict(default_headers)
+    headers.setdefault("User-Agent", f"{service_name}/{get_package_version()}")
+    if user_headers:
+        headers.update(user_headers)
+    return headers
+
+
+def get_package_version(package_name: str = "finalsa-http-client") -> str:
+    """Return the installed package version or a sensible fallback in dev mode."""
+    try:
+        return metadata.version(package_name)
+    except metadata.PackageNotFoundError:
+        return "0.0.0"
+

finalsa_common_http_client-0.0.1/finalsa/http/async/__init__.py

@@ -0,0 +1,3 @@
+from .base import BaseAsyncHttpClient
+
+__all__ = ["BaseAsyncHttpClient"]

finalsa_common_http_client-0.0.1/finalsa/http/async/base.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import aiohttp
+from aiohttp import ClientSession, ClientTimeout
+
+from finalsa.http import _shared as shared
+
+
+class BaseAsyncHttpClient:
+    """Reusable aiohttp-based HTTP client with sane defaults."""
+
+    DEFAULT_HEADERS: Mapping[str, str] = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        timeout: float | ClientTimeout | None = None,
+        default_scheme: str = "http",
+        service_name: str = "finalsa-http-client",
+        trust_env: bool = False,
+        raise_for_status: bool = True,
+        session: ClientSession | None = None,
+    ) -> None:
+        self._default_scheme = default_scheme
+        self.base_url = shared.normalize_base_url(base_url, default_scheme)
+        self._timeout = self._normalize_timeout(timeout)
+        self._trust_env = trust_env
+        self._raise_for_status = raise_for_status
+        self._session = session
+        self._owns_session = session is None
+        self._default_headers = shared.build_default_headers(
+            self.DEFAULT_HEADERS,
+            default_headers,
+            service_name,
+        )
+
+    async def __aenter__(self) -> BaseAsyncHttpClient:
+        await self._ensure_session()
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:  # type: ignore[override]
+        await self.close()
+
+    @property
+    def session(self) -> ClientSession | None:
+        """Return the underlying aiohttp session, if it has been created."""
+        return self._session
+
+    @property
+    def default_headers(self) -> Mapping[str, str]:
+        """Return a copy of the default headers."""
+        return dict(self._default_headers)
+
+    def update_default_headers(self, headers: Mapping[str, str]) -> None:
+        """Update the headers that will be sent with every request."""
+        if not headers:
+            return
+        self._default_headers.update(headers)
+
+    def build_url(self, path_or_url: str) -> str:
+        """Resolve the final URL for a request."""
+        return shared.build_url(
+            path=path_or_url,
+            url=None,
+            base_url=self.base_url,
+            default_scheme=self._default_scheme,
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str | None = None,
+        *,
+        url: str | None = None,
+        headers: Mapping[str, str] | None = None,
+        params: Mapping[str, str | int | float | None] | None = None,
+        json: Any | None = None,
+        data: Any | None = None,
+        timeout: float | ClientTimeout | None = None,
+        **kwargs: Any,
+    ) -> aiohttp.ClientResponse:
+        """Send an HTTP request using aiohttp.ClientSession.request."""
+        if path is None and url is None:
+            raise ValueError("Either 'path' or 'url' must be provided.")
+
+        session = await self._ensure_session()
+        resolved_url = shared.build_url(
+            path=path,
+            url=url,
+            base_url=self.base_url,
+            default_scheme=self._default_scheme,
+        )
+        merged_headers = shared.merge_headers(self._default_headers, headers)
+        request_timeout = self._normalize_timeout(timeout) or self._timeout
+
+        return await session.request(
+            method.upper(),
+            resolved_url,
+            headers=merged_headers,
+            params=params,
+            json=json,
+            data=data,
+            timeout=request_timeout,
+            **kwargs,
+        )
+
+    async def get(self, path: str, **kwargs: Any) -> aiohttp.ClientResponse:
+        return await self.request("GET", path, **kwargs)
+
+    async def post(self, path: str, **kwargs: Any) -> aiohttp.ClientResponse:
+        return await self.request("POST", path, **kwargs)
+
+    async def put(self, path: str, **kwargs: Any) -> aiohttp.ClientResponse:
+        return await self.request("PUT", path, **kwargs)
+
+    async def patch(self, path: str, **kwargs: Any) -> aiohttp.ClientResponse:
+        return await self.request("PATCH", path, **kwargs)
+
+    async def delete(self, path: str, **kwargs: Any) -> aiohttp.ClientResponse:
+        return await self.request("DELETE", path, **kwargs)
+
+    async def close(self) -> None:
+        """Close the underlying aiohttp session if we created it."""
+        if self._session and self._owns_session and not self._session.closed:
+            await self._session.close()
+        if self._owns_session:
+            self._session = None
+
+    async def _ensure_session(self) -> ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(
+                timeout=self._timeout,
+                trust_env=self._trust_env,
+                raise_for_status=self._raise_for_status,
+            )
+        return self._session
+
+    def _normalize_timeout(
+        self,
+        timeout: float | ClientTimeout | None,
+    ) -> ClientTimeout | None:
+        if timeout is None:
+            return None
+        if isinstance(timeout, ClientTimeout):
+            return timeout
+        return ClientTimeout(total=timeout)

finalsa_common_http_client-0.0.1/finalsa/http/sync/__init__.py

@@ -0,0 +1 @@
+from .base import BaseSyncHttpClient as BaseSyncHttpClient

finalsa_common_http_client-0.0.1/finalsa/http/sync/base.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import requests
+
+from finalsa.http import _shared as shared
+
+
+class BaseSyncHttpClient:
+    """Reusable requests-based HTTP client with sane defaults."""
+
+    DEFAULT_HEADERS: Mapping[str, str] = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        timeout: float | tuple[float, float] | None = None,
+        default_scheme: str = "http",
+        service_name: str = "finalsa-http-client",
+        trust_env: bool = True,
+        raise_for_status: bool = True,
+        session: requests.Session | None = None,
+    ) -> None:
+        self._default_scheme = default_scheme
+        self.base_url = shared.normalize_base_url(base_url, default_scheme)
+        self._timeout = timeout
+        self._trust_env = trust_env
+        self._raise_for_status = raise_for_status
+        self._session = session
+        self._owns_session = session is None
+        self._default_headers = shared.build_default_headers(
+            self.DEFAULT_HEADERS,
+            default_headers,
+            service_name,
+        )
+
+    def __enter__(self) -> BaseSyncHttpClient:
+        self._ensure_session()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:  # type: ignore[override]
+        self.close()
+
+    @property
+    def session(self) -> requests.Session | None:
+        """Return the underlying requests session, if it has been created."""
+        return self._session
+
+    @property
+    def default_headers(self) -> Mapping[str, str]:
+        """Return a copy of the default headers."""
+        return dict(self._default_headers)
+
+    def update_default_headers(self, headers: Mapping[str, str]) -> None:
+        """Update the headers that will be sent with every request."""
+        if not headers:
+            return
+        self._default_headers.update(headers)
+
+    def build_url(self, path_or_url: str) -> str:
+        """Resolve the final URL for a request."""
+        return shared.build_url(
+            path=path_or_url,
+            url=None,
+            base_url=self.base_url,
+            default_scheme=self._default_scheme,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str | None = None,
+        *,
+        url: str | None = None,
+        headers: Mapping[str, str] | None = None,
+        params: Mapping[str, str | int | float | None] | None = None,
+        json: Any | None = None,
+        data: Any | None = None,
+        timeout: float | tuple[float, float] | None = None,
+        **kwargs: Any,
+    ) -> requests.Response:
+        """Send an HTTP request using requests.Session.request."""
+        if path is None and url is None:
+            raise ValueError("Either 'path' or 'url' must be provided.")
+
+        session = self._ensure_session()
+        resolved_url = shared.build_url(
+            path=path,
+            url=url,
+            base_url=self.base_url,
+            default_scheme=self._default_scheme,
+        )
+        merged_headers = shared.merge_headers(self._default_headers, headers)
+        request_timeout = timeout if timeout is not None else self._timeout
+
+        response = session.request(
+            method.upper(),
+            resolved_url,
+            headers=merged_headers,
+            params=params,
+            json=json,
+            data=data,
+            timeout=request_timeout,
+            **kwargs,
+        )
+        if self._raise_for_status:
+            response.raise_for_status()
+        return response
+
+    def get(self, path: str, **kwargs: Any) -> requests.Response:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> requests.Response:
+        return self.request("POST", path, **kwargs)
+
+    def put(self, path: str, **kwargs: Any) -> requests.Response:
+        return self.request("PUT", path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> requests.Response:
+        return self.request("PATCH", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> requests.Response:
+        return self.request("DELETE", path, **kwargs)
+
+    def close(self) -> None:
+        """Close the underlying requests session if we created it."""
+        if self._session and self._owns_session:
+            self._session.close()
+            self._session = None
+
+    def _ensure_session(self) -> requests.Session:
+        if self._session is None:
+            session = requests.Session()
+            session.trust_env = self._trust_env
+            self._session = session
+        return self._session

finalsa_common_http_client-0.0.1/pyproject.toml

@@ -0,0 +1,121 @@
+[project]
+name = "finalsa-common-http-client"
+version = "0.0.1"
+description = "HTTP client library for common data types used in business applications"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "aiohttp>=3.10.5",
+    "fastapi>=0.116.1",
+    "finalsa-traceability>=1.0.1",
+    "requests>=2.32.4",
+]
+authors = [
+ {name = "Luis Jimenez", email = "luis@finalsa.com"},
+]
+keywords = [
+    "http",
+    "client",
+    "finalsa"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9", 
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Internationalization",
+    "Topic :: Software Development :: Localization",
+    "Typing :: Typed",
+]
+
+
+[project.urls]
+Homepage = "https://github.com/finalsa/finalsa-http-client"
+Documentation = "https://github.com/finalsa/finalsa-http-client#readme"
+Repository = "https://github.com/finalsa/finalsa-http-client.git"
+Issues = "https://github.com/finalsa/finalsa-http-client/issues"
+Changelog = "https://github.com/finalsa/finalsa-http-client/blob/main/CHANGELOG.md"
+
+[project.license]
+name = "MIT"
+file = "LICENSE.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "finalsa/http/async/*.py",
+  "finalsa/http/sync/*.py",
+  "finalsa/http/_shared.py",
+]
+
+[tool.hatch.build.targets.wheel]
+include = [
+  "finalsa/http/async/*.py",
+  "finalsa/http/sync/*.py",
+  "finalsa/http/_shared.py",
+]
+
+[dependency-groups]
+test = [
+    "coverage>=7.9.2",
+    "pytest>=8.3.4",
+    "pytest-asyncio>=0.24.0",
+]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]
+markers = [
+    "asyncio: mark tests that require an event loop",
+]
+asyncio_mode = "auto"
+
+[tool.ruff]
+# Exclude examples directory from ruff checks since they have optional dependencies
+exclude = [
+    "examples/**",
+    "htmlcov/**",
+    "*.egg-info/**",
+    ".venv/**",
+    "build/**",
+    "dist/**",
+]
+
+# Configure line length and target Python version
+line-length = 88
+target-version = "py39"
+
+[tool.ruff.lint]
+# Enable common lint rules
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings  
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+]
+
+# Ignore specific rules that might be too strict for this project
+ignore = [
+    "E501",  # line too long (handled by line-length setting)
+    "UP006",  # pyupgrade: use f-string
+    "UP035",  # pyupgrade: use f-string for single-line format
+]
+
+[tool.ruff.format]
+# Use double quotes and trailing commas
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false