ace.core.graphql
ACE Core GraphQL Builder Module
This module provides a fluent API for building GraphQL queries and mutations.
- Example usage:
from ace.core.graphql import MutationBuilder, QueryBuilder
# Build a mutation request = (
MutationBuilder(“updateLead”) .variable(“lead”, “UpdateLeadInput!”, required=True) .operation(“updateLead”, args={“lead”: “$lead”}) .select(“leadId”, “leadNumber”, “name”) .build()
)
# Build a query request = (
QueryBuilder(“getPolicies”) .variable(“ids”, “[Int!]!”, required=True) .operation(“policies”, args={“ids”: “$ids”}) .select(“policyId”, “policyNumber”) .build()
)
# Conditional fields with directives request = (
MutationBuilder(“createTransaction”) .variable(“includeMetadata”, “Boolean!”, required=True) .variable(“metadata”, “[MetadataInstanceInput!]!”, required=True) … .nested(“addMetadata”, args={“metadata”: “$metadata”})
.include_if(“$includeMetadata”) .select(“entityType”) .nested(“data”).select(“key”, “value”).end()
.end() .build()
)
- class ace.core.graphql.MutationBuilder(name: str | None = None)[source]
Bases:
OperationBuilderBuilder 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.QueryBuilder(name: str | None = None)[source]
Bases:
OperationBuilderBuilder 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
- class ace.core.graphql.GraphQLRequest(query: str, operation_name: str | None = None, operation_type: str = 'query', variables: Dict[str, ~typing.Any]=<factory>)[source]
Bases:
objectRepresents a built GraphQL request ready for execution.
- query
The GraphQL query/mutation string
- Type:
str
- variables
The variables to pass with the request
- Type:
Dict[str, Any]
- operation_name
The name of the operation (optional)
- Type:
str | None
- operation_type
Either ‘query’ or ‘mutation’
- Type:
str
- query: str
- operation_name: str | None = None
- operation_type: str = 'query'
- variables: Dict[str, Any]
- to_dict() Dict[str, Any][source]
Convert request to dictionary format for HTTP payload.
- with_variables(variables: Dict[str, Any]) GraphQLRequest[source]
Create a new request with the given variables.
- Parameters:
variables – Dictionary of variable values
- Returns:
New GraphQLRequest with variables set
- __init__(query: str, operation_name: str | None = None, operation_type: str = 'query', variables: Dict[str, ~typing.Any]=<factory>) None
- class ace.core.graphql.SelectionSet(*fields: str, nested: Dict[str, SelectionSet] | None = None)[source]
Bases:
objectRepresents a reusable GraphQL selection set.
Can be used standalone or merged into builders using .use()
Example
# Define a reusable selection POLICY_INFO = SelectionSet(
“policyId”, “policyNumber”, “effectiveDate”, nested={“coverages”: SelectionSet(“id”, “coverageNumber”)}
)
# Use in builder builder.nested(“info”).use(POLICY_INFO).end()
- __init__(*fields: str, nested: Dict[str, SelectionSet] | None = None)[source]
Initialize a SelectionSet.
- Parameters:
*fields – Scalar field names to select
nested – Dictionary of nested field name -> SelectionSet
- add_field(field: str) SelectionSet[source]
Add a scalar field to the selection.
- add_nested(name: str, selection: SelectionSet) SelectionSet[source]
Add a nested selection.
- merge(other: SelectionSet) SelectionSet[source]
Merge another SelectionSet into this one.
- Parameters:
other – SelectionSet to merge
- Returns:
Self for chaining
- build(indent: int = 0) str[source]
Build the selection set string.
- Parameters:
indent – Current indentation level (for formatting)
- Returns:
GraphQL selection set string
- class ace.core.graphql.Directive(name: str, args: Dict[str, Any] | None = None)[source]
Bases:
objectRepresents a GraphQL directive (e.g., @include, @skip, @deprecated).
- Parameters:
name – Directive name (without @)
args – Directive arguments
Example
Directive(“include”, {“if”: “$includeMetadata”}) -> @include(if: $includeMetadata) Directive(“skip”, {“if”: “$hideField”}) -> @skip(if: $hideField) Directive(“deprecated”, {“reason”: “Use newField”}) -> @deprecated(reason: “Use newField”)
- __init__(name: str, args: Dict[str, Any] | None = None)[source]
- build() str[source]
Build the directive string.