ace.core.graphql.builder

GraphQL Builder Module

This module provides fluent builders for constructing GraphQL queries and mutations.

Example

# Mutation request = (

MutationBuilder(“updateLead”) .variable(“lead”, “UpdateLeadInput!”, required=True) .operation(“updateLead”, args={“lead”: “$lead”}) .select(“leadId”, “name”) .build()

)

# Query request = (

QueryBuilder(“getPolicies”) .variable(“ids”, “[Int!]!”, required=True) .operation(“policies”, args={“ids”: “$ids”}) .select(“policyId”, “policyNumber”) .build()

)

class ace.core.graphql.builder.VariableDefinition(name: str, graphql_type: str, required: bool = False, default: Any = None)[source]

Bases: object

Represents a GraphQL variable definition.

__init__(name: str, graphql_type: str, required: bool = False, default: Any = None)[source]
build() → str[source]

Build the variable definition string.

class ace.core.graphql.builder.OperationBuilder(operation_type: str, operation_name: str | None = None)[source]

Bases: SelectionBuilder

Builder for a GraphQL operation (the root field of a query/mutation).

Extends SelectionBuilder to provide the same fluent API for field selection.

__init__(operation_type: str, operation_name: str | None = None)[source]

Initialize an OperationBuilder.

Parameters:

  • operation_type – Either ‘query’ or ‘mutation’

  • operation_name – Name of the operation (optional but recommended)

variable(name: str, graphql_type: str, required: bool = False, default: Any = None) → OperationBuilder[source]

Add a variable definition.

Parameters:

  • name – Variable name (without $)

  • graphql_type – GraphQL type (e.g., “Int!”, “[String!]!”, “UpdateLeadInput!”)

  • required – Whether the variable is required (adds ! if not in type)

  • default – Default value for the variable

Returns:

Self for chaining

operation(field_name: str, args: Dict[str, Any] | None = None) → OperationBuilder[source]

Set the root operation field.

Parameters:

  • field_name – Name of the root field (e.g., “updateLead”, “policies”)

  • args – Arguments for the root field

Returns:

Self for chaining

build() → GraphQLRequest[source]

Build the complete GraphQL request.

Returns:

GraphQLRequest ready for execution

end() → OperationBuilder[source]

Override to always return self at root level.

directive(name: str, args: Dict[str, Any] | None = None) → SelectionBuilder

Add a directive to this field.

This is the generic method for adding any GraphQL directive.

Parameters:

  • name – Directive name (without @)

  • args – Directive arguments

Returns:

Self for chaining

Example

.nested(“addMetadata”, args={“metadata”: “$metadata”})

.directive(“include”, {“if”: “$includeMetadata”}) .select(“entityType”)

.end()

.nested(“someField”)

.directive(“cacheControl”, {“maxAge”: 30}) .select(“id”)

.end()

include_if(variable: str) → SelectionBuilder

Add @include(if: $variable) directive to this field.

The field and its selections will only be included in the response when the variable evaluates to true.

Parameters:

variable – Boolean variable name (with or without $ prefix)

Returns:

Self for chaining

Example

.nested(“addMetadata”, args={“metadata”: “$metadata”})

.include_if(“$includeMetadata”) .select(“entityType”) .nested(“data”).select(“key”, “value”).end()

.end()

nested(field_name: str, args: Dict[str, Any] | None = None) → SelectionBuilder

Add a nested field selection.

Parameters:

  • field_name – Name of the nested field

  • args – Arguments for the nested field (for operations like linkParticipants)

Returns:

New SelectionBuilder for the nested field

select(*fields: str) → SelectionBuilder

Add scalar fields to the selection.

Parameters:

*fields – Field names to select

Returns:

Self for chaining

skip_if(variable: str) → SelectionBuilder

Add @skip(if: $variable) directive to this field.

The field and its selections will be skipped (excluded from response) when the variable evaluates to true.

Parameters:

variable – Boolean variable name (with or without $ prefix)

Returns:

Self for chaining

Example

.nested(“sensitiveData”)

.skip_if(“$redacted”) .select(“ssn”, “taxId”)

.end()

to_selection_set() → SelectionSet

Convert this builder to a reusable SelectionSet.

Note: Directives are not preserved in SelectionSet (they are execution-time concerns).

Returns:

SelectionSet representation

use(selection: SelectionSet) → SelectionBuilder

Apply a predefined SelectionSet to this builder.

Parameters:

selection – SelectionSet to apply

Returns:

Self for chaining

class ace.core.graphql.builder.MutationBuilder(name: str | None = None)[source]

Bases: OperationBuilder

Builder specifically for GraphQL mutations.

Example

request = (

MutationBuilder(“createPolicy”) .variable(“policy”, “PolicyCreateParamsInput!”, required=True) .variable(“participants”, “[ParticipantEntityLinkCreateParamsInput!]!”, required=True) .operation(“createPolicy”, args={“policy”: “$policy”}) .select(“policyId”) .nested(“info”)

.select(“policyId”, “policyNumber”, “policyGUID”) .nested(“coverages”)

.select(“id”, “coverageNumber”)

.end()

.end() .nested(“linkParticipants”, args={“linkParticipants”: “$participants”})

.select(“id”) .nested(“party”).select(“id”).end()

.end() .build()

)

__init__(name: str | None = None)[source]

Initialize a MutationBuilder.

Parameters:

name – Name of the mutation operation (optional but recommended)

build() → GraphQLRequest

Build the complete GraphQL request.

Returns:

GraphQLRequest ready for execution

directive(name: str, args: Dict[str, Any] | None = None) → SelectionBuilder

Add a directive to this field.

This is the generic method for adding any GraphQL directive.

Parameters:

  • name – Directive name (without @)

  • args – Directive arguments

Returns:

Self for chaining

Example

.nested(“addMetadata”, args={“metadata”: “$metadata”})

.directive(“include”, {“if”: “$includeMetadata”}) .select(“entityType”)

.end()

.nested(“someField”)

.directive(“cacheControl”, {“maxAge”: 30}) .select(“id”)

.end()

end() → OperationBuilder

Override to always return self at root level.

include_if(variable: str) → SelectionBuilder

Add @include(if: $variable) directive to this field.

The field and its selections will only be included in the response when the variable evaluates to true.

Parameters:

variable – Boolean variable name (with or without $ prefix)

Returns:

Self for chaining

Example

.nested(“addMetadata”, args={“metadata”: “$metadata”})

.include_if(“$includeMetadata”) .select(“entityType”) .nested(“data”).select(“key”, “value”).end()

.end()

nested(field_name: str, args: Dict[str, Any] | None = None) → SelectionBuilder

Add a nested field selection.

Parameters:

  • field_name – Name of the nested field

  • args – Arguments for the nested field (for operations like linkParticipants)

Returns:

New SelectionBuilder for the nested field

operation(field_name: str, args: Dict[str, Any] | None = None) → OperationBuilder

Set the root operation field.

Parameters:

  • field_name – Name of the root field (e.g., “updateLead”, “policies”)

  • args – Arguments for the root field

Returns:

Self for chaining

select(*fields: str) → SelectionBuilder

Add scalar fields to the selection.

Parameters:

*fields – Field names to select

Returns:

Self for chaining

skip_if(variable: str) → SelectionBuilder

Add @skip(if: $variable) directive to this field.

The field and its selections will be skipped (excluded from response) when the variable evaluates to true.

Parameters:

variable – Boolean variable name (with or without $ prefix)

Returns:

Self for chaining

Example

.nested(“sensitiveData”)

.skip_if(“$redacted”) .select(“ssn”, “taxId”)

.end()

to_selection_set() → SelectionSet

Convert this builder to a reusable SelectionSet.

Note: Directives are not preserved in SelectionSet (they are execution-time concerns).

Returns:

SelectionSet representation

use(selection: SelectionSet) → SelectionBuilder

Apply a predefined SelectionSet to this builder.

Parameters:

selection – SelectionSet to apply

Returns:

Self for chaining

variable(name: str, graphql_type: str, required: bool = False, default: Any = None) → OperationBuilder

Add a variable definition.

Parameters:

  • name – Variable name (without $)

  • graphql_type – GraphQL type (e.g., “Int!”, “[String!]!”, “UpdateLeadInput!”)

  • required – Whether the variable is required (adds ! if not in type)

  • default – Default value for the variable

Returns:

Self for chaining

class ace.core.graphql.builder.QueryBuilder(name: str | None = None)[source]

Bases: OperationBuilder

Builder specifically for GraphQL queries.

Example

request = (

QueryBuilder(“getPolicies”) .variable(“ids”, “[Int!]!”, required=True) .operation(“policies”, args={“ids”: “$ids”}) .select(“policyId”, “policyNumber”) .nested(“product”)

.select(“productTypeId”) .nested(“carrierName”).select(“default”).end()

.end() .build()

)

__init__(name: str | None = None)[source]

Initialize a QueryBuilder.

Parameters:

name – Name of the query operation (optional but recommended)

build() → GraphQLRequest

Build the complete GraphQL request.

Returns:

GraphQLRequest ready for execution

directive(name: str, args: Dict[str, Any] | None = None) → SelectionBuilder

Add a directive to this field.

This is the generic method for adding any GraphQL directive.

Parameters:

  • name – Directive name (without @)

  • args – Directive arguments

Returns:

Self for chaining

Example

.nested(“addMetadata”, args={“metadata”: “$metadata”})

.directive(“include”, {“if”: “$includeMetadata”}) .select(“entityType”)

.end()

.nested(“someField”)

.directive(“cacheControl”, {“maxAge”: 30}) .select(“id”)

.end()

end() → OperationBuilder

Override to always return self at root level.

include_if(variable: str) → SelectionBuilder

Add @include(if: $variable) directive to this field.

The field and its selections will only be included in the response when the variable evaluates to true.

Parameters:

variable – Boolean variable name (with or without $ prefix)

Returns:

Self for chaining

Example

.nested(“addMetadata”, args={“metadata”: “$metadata”})

.include_if(“$includeMetadata”) .select(“entityType”) .nested(“data”).select(“key”, “value”).end()

.end()

nested(field_name: str, args: Dict[str, Any] | None = None) → SelectionBuilder

Add a nested field selection.

Parameters:

  • field_name – Name of the nested field

  • args – Arguments for the nested field (for operations like linkParticipants)

Returns:

New SelectionBuilder for the nested field

operation(field_name: str, args: Dict[str, Any] | None = None) → OperationBuilder

Set the root operation field.

Parameters:

  • field_name – Name of the root field (e.g., “updateLead”, “policies”)

  • args – Arguments for the root field

Returns:

Self for chaining

select(*fields: str) → SelectionBuilder

Add scalar fields to the selection.

Parameters:

*fields – Field names to select

Returns:

Self for chaining

skip_if(variable: str) → SelectionBuilder

Add @skip(if: $variable) directive to this field.

The field and its selections will be skipped (excluded from response) when the variable evaluates to true.

Parameters:

variable – Boolean variable name (with or without $ prefix)

Returns:

Self for chaining

Example

.nested(“sensitiveData”)

.skip_if(“$redacted”) .select(“ssn”, “taxId”)

.end()

to_selection_set() → SelectionSet

Convert this builder to a reusable SelectionSet.

Note: Directives are not preserved in SelectionSet (they are execution-time concerns).

Returns:

SelectionSet representation

use(selection: SelectionSet) → SelectionBuilder

Apply a predefined SelectionSet to this builder.

Parameters:

selection – SelectionSet to apply

Returns:

Self for chaining

variable(name: str, graphql_type: str, required: bool = False, default: Any = None) → OperationBuilder

Add a variable definition.

Parameters:

  • name – Variable name (without $)

  • graphql_type – GraphQL type (e.g., “Int!”, “[String!]!”, “UpdateLeadInput!”)

  • required – Whether the variable is required (adds ! if not in type)

  • default – Default value for the variable

Returns:

Self for chaining