Sync Compatibility Wrapper

[btoron]

Overview

Implement a compatibility wrapper (OFSCCompat) in ofsc/compat.py that allows existing synchronous OFSC client code to continue working in OFSC 3.0 while using AsyncOFSC internally.

In OFSC 3.0, the OFSC class will become an alias for OFSCCompat, so existing code continues to work without modification — but with a DeprecationWarning.

Background

When this issue was originally filed, the sync and async clients had similar method coverage. The async client has since grown to ~200 methods while the sync client covers ~97. The compatibility wrapper must cover the full async surface, not just the original sync subset.

Design Decisions

1. Method Scope

Wrap all ~200 async methods across all API modules:

• core — Activities, Resources, Users, Events, Daily Extract, Subscriptions
• metadata — Properties, Workzones, Workskills, Activity Types, Routing Profiles, etc.
• capacity — Available capacity and quota
• oauth2 — Token management

2. Async Execution Strategy

Use asyncio.run() per call. No thread pool or persistent event loop.

def get_workzones(self, offset=0, limit=100, **kwargs):
    return asyncio.run(self._async_impl.get_workzones(offset=offset, limit=limit))

3. response_type Deprecation

The existing response_type parameter (FULL_RESPONSE, OBJ_RESPONSE, TEXT_RESPONSE) is a sync-only concept. In the compat wrapper:

• All response_type values are deprecated and will emit DeprecationWarning when used.
• For FULL_RESPONSE: return a RequestsResponseAdapter (see below) wrapping the httpx.Response to mimic requests.Response.
• For OBJ_RESPONSE (default): return the Pydantic model as normal.
• For TEXT_RESPONSE: return response.text.

The constants FULL_RESPONSE, OBJ_RESPONSE, TEXT_RESPONSE, and the wrap_return helper are deprecated alongside the sync client.

4. RequestsResponseAdapter

A thin wrapper around httpx.Response that mimics the requests.Response interface for users who rely on response_type=FULL_RESPONSE:

class RequestsResponseAdapter:
    """Wraps httpx.Response to mimic requests.Response interface."""
    def __init__(self, httpx_response: httpx.Response): ...

    @property
    def status_code(self) -> int: ...

    @property
    def text(self) -> str: ...

    def json(self) -> dict: ...

    @property
    def headers(self) -> dict: ...

    @property
    def content(self) -> bytes: ...

    @property
    def ok(self) -> bool: ...

5. File Location

New file: ofsc/compat.py

In OFSC 3.0, ofsc/__init__.py will re-export:

from ofsc.compat import OFSCCompat as OFSC

6. Deprecation Warning

Emit DeprecationWarning on instantiation of OFSC / OFSCCompat:

warnings.warn(
    "OFSC sync client is deprecated and will be removed in OFSC 4.0. "
    "Use AsyncOFSC instead.",
    DeprecationWarning,
    stacklevel=2,
)

Architecture Sketch

# ofsc/compat.py

class RequestsResponseAdapter:
    """Wraps httpx.Response to mimic requests.Response interface."""
    ...

class _SyncModuleWrapper:
    """Generic wrapper that converts async module methods to sync."""
    def __init__(self, async_module):
        self._async = async_module

    def __getattr__(self, name):
        attr = getattr(self._async, name)
        if asyncio.iscoroutinefunction(attr):
            def sync_wrapper(*args, **kwargs):
                response_type = kwargs.pop("response_type", None)
                if response_type is not None:
                    warnings.warn("response_type is deprecated...", DeprecationWarning, stacklevel=2)
                result = asyncio.run(attr(*args, **kwargs))
                # Handle response_type adaptation here
                return result
            return sync_wrapper
        return attr

class OFSCCompat:
    """Synchronous compatibility wrapper for AsyncOFSC."""

    def __init__(self, clientID, secret, companyName, **kwargs):
        warnings.warn("OFSC sync client is deprecated...", DeprecationWarning, stacklevel=2)
        self._async_client = AsyncOFSC(clientID=clientID, secret=secret, companyName=companyName, **kwargs)
        ...

    @property
    def core(self): ...

    @property
    def metadata(self): ...

    @property
    def capacity(self): ...

    @property
    def oauth2(self): ...

Testing Requirements

• OFSCCompat instantiation emits DeprecationWarning
• All module wrappers (core, metadata, capacity, oauth2) are accessible
• Async methods can be called synchronously via the wrapper
• response_type=FULL_RESPONSE returns a RequestsResponseAdapter
• response_type=OBJ_RESPONSE returns the Pydantic model (with deprecation warning)
• response_type=TEXT_RESPONSE returns response text (with deprecation warning)
• RequestsResponseAdapter exposes status_code, text, json(), headers, content, ok
• Passing response_type emits DeprecationWarning
• Existing sync client test suite passes using OFSCCompat

Migration Path

# Before (OFSC 2.x sync)
instance = OFSC(clientID=..., secret=..., companyName=...)
workzones = instance.metadata.get_workzones()

# After (OFSC 3.0+ async — recommended)
async with AsyncOFSC(clientID=..., secret=..., companyName=...) as client:
    workzones = await client.metadata.get_workzones()

# Compat (OFSC 3.0 — works but deprecated)
instance = OFSC(clientID=..., secret=..., companyName=...)  # DeprecationWarning
workzones = instance.metadata.get_workzones()               # Works via asyncio.run()

Related

• ofsc/async_client/ — source of all wrapped methods
• README deprecation notice: "Future Deprecation Notice - OFSC 3.0"
• FULL_RESPONSE, OBJ_RESPONSE, TEXT_RESPONSE, wrap_return in ofsc/__init__.py

[btoron]

RequestsResponseAdapter Full Implementation

Here is the complete implementation for the RequestsResponseAdapter class that wraps an httpx.Response to expose the requests.Response interface:

from __future__ import annotations

import json as _json
from typing import Any, Optional

import httpx
import requests


class RequestsResponseAdapter:
    """Wraps an httpx.Response to expose the requests.Response interface.

    Used by the sync compatibility wrapper so that callers using
    ``FULL_RESPONSE`` continue to receive an object with the familiar
    ``requests.Response`` API even though the underlying transport has
    moved to httpx.
    """

    def __init__(self, response: httpx.Response) -> None:
        self._response = response

    # ------------------------------------------------------------------
    # Core properties
    # ------------------------------------------------------------------

    @property
    def status_code(self) -> int:
        return self._response.status_code

    @property
    def text(self) -> str:
        return self._response.text

    @property
    def content(self) -> bytes:
        return self._response.content

    @property
    def headers(self) -> httpx.Headers:
        # httpx.Headers is a case-insensitive multidict — compatible with
        # code that does ``response.headers["Content-Type"]``.
        return self._response.headers

    @property
    def encoding(self) -> Optional[str]:
        return self._response.encoding

    @property
    def url(self) -> str:
        return str(self._response.url)

    @property
    def elapsed(self):
        """Return elapsed time as a timedelta (same type as requests)."""
        return self._response.elapsed

    @property
    def cookies(self) -> httpx.Cookies:
        # httpx.Cookies supports the same dict-like access as
        # requests.cookies.RequestsCookieJar.
        return self._response.cookies

    # ------------------------------------------------------------------
    # Status helpers
    # ------------------------------------------------------------------

    @property
    def ok(self) -> bool:
        """True when status_code < 400 (mirrors requests.Response.ok)."""
        return self._response.is_success

    @property
    def reason(self) -> str:
        """HTTP reason phrase, e.g. 'OK' or 'Not Found'."""
        return self._response.reason_phrase

    # ------------------------------------------------------------------
    # Methods
    # ------------------------------------------------------------------

    def json(self, **kwargs: Any) -> Any:
        """Decode response body as JSON.

        Accepts the same keyword arguments as ``json.loads`` so that
        existing call-sites using ``response.json(object_hook=...)`` etc.
        continue to work.
        """
        if kwargs:
            return _json.loads(self._response.content, **kwargs)
        return self._response.json()

    def raise_for_status(self) -> None:
        """Raise a ``requests.HTTPError`` for 4xx/5xx responses.

        Converts the ``httpx.HTTPStatusError`` into a
        ``requests.HTTPError`` so that callers catching
        ``requests.exceptions.HTTPError`` are not broken.
        """
        try:
            self._response.raise_for_status()
        except httpx.HTTPStatusError as exc:
            raise requests.HTTPError(str(exc), response=self) from exc  # type: ignore[arg-type]

    # ------------------------------------------------------------------
    # Dunder helpers for convenience
    # ------------------------------------------------------------------

    def __repr__(self) -> str:
        return f"<RequestsResponseAdapter [{self.status_code}]>"

    def __bool__(self) -> bool:
        """Mirrors requests: truthy when status_code < 400."""
        return self.ok

Usage inside the sync compat wrapper

from ofsc.compat import RequestsResponseAdapter

# Wherever the async method returns an httpx.Response, wrap it:
raw: httpx.Response = await self._async_client.core._client.get(url, ...)
return RequestsResponseAdapter(raw)

Notes

• headers returns httpx.Headers, which is a case-insensitive mapping — drop-in compatible with code that inspects response.headers["content-type"].
• cookies returns httpx.Cookies, which supports the same response.cookies["name"] access pattern as requests.
• raise_for_status() re-raises as requests.HTTPError so existing except requests.exceptions.HTTPError blocks are not broken.
• elapsed is already a datetime.timedelta in both libraries — no conversion needed.
• The json(**kwargs) fallback to json.loads(content) handles the rare case where callers pass object_hook or other json.loads kwargs.