Utils

class Fields(fields)

Bases: object

Helper class for handling GraphQL field combinations.

This class provides structured handling of GraphQL field strings, including:

• Parsing field strings while preserving nested structures

• Combining multiple field sets while maintaining order

• Converting back to GraphQL-compatible strings

Parameters:

fields (Union[str, Fields]) – Either a space-separated string of field names or another Fields instance. Can include nested structures using GraphQL syntax.

fields

List of parsed and normalized field strings.

Example

>>> basic_fields = Fields('id name')
>>> extended_fields = basic_fields + 'description'
>>> print(extended_fields)
'id name description'

>>> nested_fields = Fields('id items { id name }')
>>> print(nested_fields)
'id items { id name }'

__add__(other)

Combine two field lists, maintaining order and preserving nested structures.

Parameters:

other (Union[Fields, str]) – Either a Fields instance or a field string to combine with this instance.

Return type:

Fields

Returns:

New Fields instance containing combined fields.

Example

>>> fields1 = Fields('id name top_group { id title }')
>>> fields2 = Fields('groups { id title }')
>>> str(fields1 + fields2)
'id name top_group { id title } groups { id title }'

__contains__(field)

Check if a field exists in the Fields instance.

Parameters:

field (str) – Field name to check for.

Return type:

bool

Returns:

True if field exists, False otherwise.

Example

>>> fields = Fields('id name')
>>> 'name' in fields
True
>>> ' name ' in fields  # Whitespace is normalized
True
>>> 'board' in fields
False

__eq__(other)

Check if two Fields instances are equal.

Parameters:

other (object) – Another object to compare with.

Return type:

bool

Returns:

True if other is a Fields instance with identical fields, False otherwise.

Example

>>> fields1 = Fields('id name')
>>> fields2 = Fields('id name')
>>> fields1 == fields2
True
>>> fields3 = Fields('id description')
>>> fields1 == fields3
False

__hash__()

Return hash value for the Fields instance.

Return type:

int

Returns:

Hash value based on the fields list.

Example

>>> fields1 = Fields('id name')
>>> fields2 = Fields('id name')
>>> hash(fields1) == hash(fields2)
True

__repr__()

Return a string representation of the Fields object.

Return type:

str

Returns:

String representation that can be used to recreate the object.

Example

>>> fields = Fields('id name')
>>> repr(fields)
"Fields('id name')"

__str__()

Convert back to a GraphQL-compatible field string.

Return type:

str

__sub__(other)

Subtract fields from another Fields object or a string.

Parameters:

other (Union[Fields, str]) – Fields instance or string containing fields to subtract.

Return type:

Fields

Returns:

New Fields instance with specified fields removed.

Example

>>> fields1 = Fields('id name board { id title }')
>>> fields2 = Fields('name board { title }')
>>> str(fields1 - fields2)
'id board { id }'

add_temp_fields(temp_fields)

Add temporary fields while preserving nested structures.

Parameters:

temp_fields (list[str]) – List of field names to temporarily add

Return type:

Fields

Returns:

New Fields instance with temporary fields added

Example

>>> fields = Fields('id name')
>>> new_fields = fields.add_temp_fields(['temp1', 'temp2'])
>>> str(new_fields)
'id name temp1 temp2'

>>> fields = Fields('name products { kind }')
>>> new_fields = fields.add_temp_fields(['id', 'products { id }'])
>>> str(new_fields)
'name id products { kind id }'

static extract_parent_fields(temp_fields)

Extract parent field names from nested temp fields.

Parameters:

temp_fields (list[str]) – List of temp field strings that may contain nested structures

Return type:

list[str]

Returns:

List of parent field names that contain the temp fields

Example

>>> Fields.extract_parent_fields(
...     ['id', 'products { id }', 'products { kind { id } }']
... )
['products']
>>> Fields.extract_parent_fields(
...     ['id', 'board { id }', 'board { items { id } }']
... )
['board']

static manage_temp_fields(data, original_fields, temp_fields, preserve_fields=None)

Remove temporary fields from query results that weren’t in original fields.

Parameters:

• data (dict[str, Any] | list[Any]) – Query result data

• original_fields (Union[str, set[str], Fields]) – Space-separated string, set of field names, or Fields object

• temp_fields (list[str]) – List of field names that were temporarily added

• preserve_fields (list[str] | None) – List of field names that should be preserved even if they’re temp fields

Return type:

dict[str, Any] | list[Any]

Returns:

Data structure with temporary fields removed if they weren’t in original fields

Example

>>> data = {
...     'id': '123456789',
...     'name': 'Task',
...     'temp_status': 'active',
...     'board': {'id': '987654321', 'temp_field': 'value'},
... }
>>> original = 'id name board { id }'
>>> temp_fields = ['temp_status', 'temp_field']
>>> Fields.manage_temp_fields(data, original, temp_fields)
{'id': '123456789', 'name': 'Task', 'board': {'id': '987654321'}}

Data Modifiers

Utility functions for modifying data structures.

update_data_in_place(data, modify_fn)

Update items in a nested data structure in place.

This function recursively traverses a nested data structure (dict or list) and applies the provided modify_fn to each item.

Parameters:

• data (dict[str, Any] | list[Any]) – The nested data structure to be modified.

• modify_fn (Callable[[dict[str, Any]], None]) – A function that will be applied to each item.

Returns:

True if the modification was applied, False otherwise. The function modifies the data structure in place.

Return type:

bool

Error Handlers

Utility functions for handling errors in Monday API interactions.

check_query_result(query_result, *, errors_only=False)

Check if the query result contains an error and raise MondayAPIError if found.

This function examines the query result dictionary for error indicators and handles them appropriately. Supports the GraphQL-compliant error format.

Parameters:

• query_result (dict[str, Any]) – The response dictionary from a monday.com API query.

• errors_only (bool) – Only check for errors, not the presence of the data key.

Return type:

dict[str, Any]

Returns:

The original query_result if no errors are found.

Raises:

MondayAPIError – If an error is found in the query result or if the response structure is unexpected.

class ErrorHandler(rate_limit_seconds=60)

Bases: object

Centralized error handler for Monday.com API errors.

Parameters:

rate_limit_seconds (int)

handle_graphql_errors(response_data, response_headers, query)

Handle GraphQL-compliant error format (2025-01+).

Return type:

None

Parameters:

• response_data (dict[str, Any])

• response_headers (dict[str, str])

• query (str)

get_retry_after_seconds(response_headers, default_seconds)

Extract retry delay from Retry-After header or return default.

Return type:

int

Parameters:

• response_headers (dict[str, str])

• default_seconds (int)

Pagination

Module for handling pagination in monday.com API requests.

This module provides utilities and types for handling paginated requests and extracting pagination-related data from API responses.

class PaginatedResult(items)

Bases: object

Type definition for paginated request results.

This structure is used by pagination utilities to return structured results from paginated API requests.

Parameters:

items (list[Any])

items: list[Any]

The list of items retrieved from the paginated request

to_dict()

Convert to dictionary for API requests.

Return type:

dict[str, Any]

classmethod from_dict(data)

Create from dictionary.

Return type:

PaginatedResult

Parameters:

data (dict[str, Any])

extract_items_page_value(data)

Recursively extract the ‘items_page’ value from a nested dictionary or list.

Parameters:

data (dict[str, Any] | list) – The dictionary or list to search.

Return type:

Any | None

Returns:

The ‘items_page’ value if found; otherwise, None.

extract_cursor_from_response(response_data)

Recursively extract the ‘cursor’ value from the response data.

Parameters:

response_data (dict[str, Any]) – The response data containing the cursor information.

Return type:

str | None

Returns:

The extracted cursor value, or None if not found.

extract_items_from_response(data)

Recursively extract items from the response data.

Parameters:

data (Any) – The response data containing the items.

Return type:

list[dict[str, Any]]

Returns:

A list of extracted items.

extract_items_from_query(query)

Extract the items block from the query string.

Parameters:

query (str) – The GraphQL query string containing the items block.

Return type:

str | None

Returns:

The items block as a string, or None if not found.

async paginated_item_request(client, query, limit=25, cursor=None)

Executes a paginated request to retrieve items from monday.com.

Parameters:

• client (MondayClientProtocol) – The MondayClient instance to execute the request.

• query (str) – The GraphQL query string.

• limit (int) – Maximum items per page.

• cursor (str | None) – Starting cursor for pagination.

Return type:

PaginatedResult

Returns:

PaginatedResult dataclass instance containing the list of retrieved items.

Raises:

PaginationError – If item extraction fails.

Query Builder

Utility functions and types for building GraphQL query strings.

ENUM_FIELDS = {'board_attribute', 'board_kind', 'column_type', 'duplicate_type', 'fields', 'group_attribute', 'kind', 'order_by', 'position_relative_method', 'query_params', 'state'}

Fields that should be treated as GraphQL enums (unquoted)

NUMERIC_ID_FIELDS = {'board_id', 'board_ids', 'folder_id', 'group_id', 'group_ids', 'ids', 'item_id', 'item_ids', 'owner_ids', 'parent_item_id', 'relative_to', 'subitem_id', 'subitem_ids', 'subscriber_ids', 'subscriber_teams_ids', 'template_id', 'workspace_id', 'workspace_ids'}

Fields that should be treated as numeric IDs (unquoted when they are numeric strings)

build_graphql_query(operation, query_type, args=None)

Builds a formatted GraphQL query string based on the provided parameters.

Parameters:

• operation (str) – The GraphQL operation name (e.g., ‘items’, ‘create_item’)

• query_type (Literal['query', 'mutation']) – The type of GraphQL operation (‘query’ or ‘mutation’)

• args (dict[str, Any] | None) – GraphQL query arguments

Return type:

str

Returns:

A formatted GraphQL query string ready for API submission

build_operation_with_variables(operation, query_type, variable_types, arg_var_mapping, fields, *, arg_literals=None)

Build a GraphQL operation string using variables.

Parameters:

• operation (str) – Operation name (e.g., ‘create_board’)

• query_type (Literal['query', 'mutation']) – ‘query’ or ‘mutation’

• variable_types (dict[str, str]) – Mapping of variable name -> GraphQL type (e.g., ‘name’: ‘String!’)

• arg_var_mapping (dict[str, str]) – Mapping of argument name -> variable name (e.g., ‘board_name’: ‘name’)

• fields (Any) – Selection set fields (string or Fields-like)

• arg_literals (dict[str, str] | None) – Literal argument strings to include verbatim (e.g., formatted lists)

Return type:

str

Returns:

GraphQL operation string with variable definitions and arguments bound to variables.

format_columns_mapping(mapping)

Format columns mapping dict to GraphQL argument value.

Input: {‘source_col’: ‘target_col’} Output: [{source: “source_col”, target: “target_col”}, …]

Return type:

str

Parameters:

mapping (dict[str, Any])

build_query_params_string(query_params)

Builds a GraphQL-compatible query parameters string.

Parameters:

query_params (QueryParams | dict[str, Any] | None) – QueryParams dataclass or dictionary containing rules, operator and order_by parameters

Return type:

str

Returns:

Formatted query parameters string for GraphQL query

map_hex_to_color(color_hex)

Maps a color’s hex value to its string representation in monday.com.

Parameters:

color_hex (str) – The hex representation of the color

Return type:

str

Returns:

The string representation of the color used by monday.com

Logging

Convenience helpers for configuring the library’s logging.

enable_logging(level=20, format_string=None, handler=None)

Enable logging for the Monday client with a dedicated handler.

This function removes any existing NullHandlers and adds a StreamHandler (or custom handler) to the Monday logger. It also ensures propagation is enabled, making it safe to call after disable_logging().

Parameters:

• level (int | str) – Log level (e.g., logging.DEBUG, logging.INFO, ‘DEBUG’, ‘INFO’)

• format_string (str | None) – Custom format string for log messages. Defaults to ‘%(asctime)s - %(name)s - %(levelname)s - %(message)s’

• handler (Handler | None) – Custom handler to use. Defaults to StreamHandler(sys.stdout)

Return type:

None

Note

• Calling this multiple times won’t create duplicate handlers

• Always sets propagate=True, overriding any previous disable_logging() call

• If you prefer external logging configuration, use configure_for_external_logging() instead

Example

>>> from monday import enable_logging
>>> enable_logging(level='DEBUG')
>>> # or with specific format
>>> enable_logging(level='INFO', format_string='%(name)s: %(message)s')

disable_logging()

Completely disable logging for the Monday client.

This function removes all existing handlers, adds a NullHandler, and sets propagate=False to ensure no Monday client logs appear anywhere, even if the root logger is configured.

Note

• This completely silences Monday client logs, regardless of your app’s logging setup

• To re-enable logging, call enable_logging() which will restore normal behavior

• More aggressive than just setting a high log level

Example

>>> from monday import disable_logging
>>> disable_logging()
>>> # Monday client will produce no log output

Return type:

None

set_log_level(level)

Set the log level for the Monday client logger.

This only changes the level - it doesn’t add or remove handlers. Use enable_logging() or configure_for_external_logging() first to ensure the logger has appropriate handlers.

Parameters:

level (int | str) – Log level (e.g., logging.DEBUG, logging.INFO, ‘DEBUG’, ‘INFO’)

Return type:

None

Note

• If the Monday logger only has a NullHandler, changing the level won’t make logs appear

• Use this to fine-tune logging verbosity after setting up handlers

Example

>>> from monday import enable_logging, set_log_level
>>> enable_logging()  # Set up handlers first
>>> set_log_level('DEBUG')  # Now change level
>>> set_log_level('WARNING')  # Reduce verbosity

get_logger()

Get the Monday client logger instance.

This returns the same logger instance used internally by the Monday client. Useful for advanced logging configuration or adding custom handlers.

Return type:

Logger

Returns:

The Monday client logger (equivalent to logging.getLogger(‘monday’))

Note

• This is the same logger that enable_logging() and disable_logging() modify

• You can use this for direct logger manipulation if the utility functions don’t meet your needs

• Changes to this logger affect all Monday client logging

Example

>>> from monday import get_logger
>>> logger = get_logger()
>>> logger.addHandler(your_custom_handler)
>>> logger.info('Custom log message')

is_logging_enabled()

Check if logging is currently enabled for the Monday client.

This checks whether the Monday logger has any handlers other than NullHandler. Note that even with only a NullHandler, logs may still appear if propagate=True and a parent logger (like root) has handlers configured.

Return type:

bool

Returns:

True if the Monday logger has non-NullHandler handlers, False otherwise

Note

• Returns False if only NullHandler is present, even if logs might still appear via propagation

• Use this to check if enable_logging() has been called successfully

• Does not account for external logging configuration via configure_for_external_logging()

Example

>>> from monday import is_logging_enabled, enable_logging
>>> print(is_logging_enabled())  # False initially
>>> enable_logging()
>>> print(is_logging_enabled())  # True after enabling

configure_for_external_logging()

Prepare the Monday client logger for external logging configuration.

This removes the default NullHandler and sets the logger level to NOTSET, allowing the logger to inherit configuration from parent loggers or be configured via logging.config.dictConfig().

Use this when you want to manage Monday client logging through your application’s centralized logging configuration instead of enable_logging().

Note

• After calling this, Monday logs will appear if your app configures logging (via basicConfig, dictConfig, etc.)

• Sets level to NOTSET for proper inheritance

• Keeps propagate=True to allow inheritance from parent loggers

• Required when using dictConfig() with explicit Monday logger configuration

Example

>>> from monday import configure_for_external_logging
>>> import logging
>>> configure_for_external_logging()
>>> logging.basicConfig(level=logging.INFO)  # Monday logs will now appear
>>> # Or with dictConfig:
>>> configure_for_external_logging()
>>> logging.config.dictConfig(
...     your_config
... )  # Configure Monday logger in your_config

Return type:

None