Synchronous Usage

This page documents the optional synchronous API provided by SyncMondayClient and the top-level helpers sync(), run_sync(), and to_sync().

When to use

• You are not using asyncio but want to call the async Monday API client.

• You prefer a blocking API surface while preserving the same service design.

What it provides

• SyncMondayClient: mirrors MondayClient services but executes coroutine-returning methods on a dedicated background event loop.

• sync(): convenience factory that returns a SyncMondayClient.

• run_sync(): run a single coroutine to completion without managing an event loop.

• to_sync(): wrap an async def function so you can call it synchronously.

Quick start

from monday import sync

client = sync(api_key='your_api_key')
items = client.items.query(item_ids=[123])  # blocking call
with client.use_api_key('another_token'):
    board = client.boards.query(board_ids=[456])
client.close()

Header override contexts

• use_headers(): Synchronous context manager that applies temporary headers to awaited calls made inside the with block.

• use_api_key(): Synchronous shorthand for overriding the Authorization header.

• Contexts are stackable; later (inner) overrides take precedence on key conflicts.

with client.use_headers({'X-Trace': 'outer', 'Authorization': 'Bearer A'}):
    # headers include X-Trace=outer, Authorization=Bearer A
    with client.use_api_key('B'):
        # headers include X-Trace=outer, Authorization=Bearer B
        ...
    # back to Authorization=Bearer A

Performance and threading notes

• Each SyncMondayClient instance owns a dedicated background event loop running in a daemon thread.

• Prefer reusing a single instance rather than repeatedly constructing/destroying clients.

• The facade is intended for non-async callers. Avoid calling it from within an event loop running on the same thread.

Top-level helpers

from monday import run_sync, to_sync

async def compute(x):
    return x * 2

assert run_sync(compute(21)) == 42

compute_sync = to_sync(compute)
assert compute_sync(21) == 42

Testing guidance

• When writing tests for code using SyncMondayClient, mock or stub AiohttpAdapter.post (or HttpxAdapter.post) to avoid real network calls.

• Use nested use_headers() contexts to test header propagation and override precedence.

API reference

class SyncMondayClient(config=None, *, api_key=None, url='https://api.monday.com/v2', version=None, headers=None, max_retries=4, transport='aiohttp')

Bases: object

Synchronous facade for MondayClient.

This class constructs an underlying async MondayClient and exposes the same services, but methods can be called synchronously. Internally, calls are executed on a background asyncio event loop.

Parameters:

• config (Config | None)

• api_key (str | None)

• url (str)

• version (str | None)

• headers (dict[str, Any] | None)

• max_retries (int)

• transport (str)

__enter__()

Support with SyncMondayClient(…) as c:; returns self.

Return type:

Self

__exit__(exc_type, exc, tb)

Close the client when leaving a context manager block.

Return type:

None

property api_key: str

Current API key used for Authorization.

close()

Shut down the background event loop and release resources.

Return type:

None

property headers: dict[str, Any]

Default HTTP headers applied to requests.

property max_retries: int

Maximum retry attempts for failed requests.

post_request(query, variables=None)

Execute a GraphQL request synchronously and return the response.

Return type:

dict[str, Any]

Parameters:

• query (str)

• variables (dict[str, Any] | None)

property url: str

Base URL for the Monday GraphQL API.

use_api_key(api_key)

Synchronous context manager to temporarily override Authorization header for calls inside the with block.

Return type:

Generator[Self, Any, None]

Parameters:

api_key (str)

use_headers(headers)

Synchronous context manager to temporarily override headers for calls inside the with block.

Return type:

Generator[Self, Any, None]

Parameters:

headers (dict[str, Any])

property version: str | None

Pinned API version (e.g., ‘2024-10’), if configured.

sync(config=None, **kwargs)

Create a synchronous Monday client.

This is a convenience factory for SyncMondayClient for users not using asyncio.

Parameters:

• config (Config | None) – Optional Config object.

• **kwargs (Any) – Keyword arguments forwarded to SyncMondayClient such as api_key, url, version, headers, max_retries, and transport.

Return type:

SyncMondayClient

Returns:

A ready-to-use SyncMondayClient instance.

run_sync(awaitable)

Run a coroutine/awaitable to completion in a temporary background loop.

Useful for one-off calls when you have an async function but are in a synchronous context.

Return type:

TypeVar(T)

Parameters:

awaitable (Awaitable)

Example

>>> async def fetch():
...     return 42
>>> run_sync(fetch())
42

Note

If you need to call multiple async functions efficiently, prefer constructing a SyncMondayClient and reusing its background loop, as this helper spins up a fresh loop each time.

to_sync(fn)

Convert an async function into a blocking callable using run_sync.

Return type:

Callable[[ParamSpec(P)], TypeVar(T)]

Parameters:

fn (Callable[[P], Awaitable])

Example

>>> async def fetch():
...     return 42
>>> fetch_sync = to_sync(fetch)
>>> fetch_sync()
42