ace.core.graphql.selection

GraphQL Selection Set Module

This module provides classes for building GraphQL selection sets, including support for nested fields, predefined selections, and directives.

Directives:

Supports @include, @skip, and custom directives on nested fields.

# Using shortcuts builder.nested(“addMetadata”, args={“metadata”: “$metadata”})

.include_if(“$includeMetadata”) .select(“entityType”)

.end()

# Using generic directive builder.nested(“someField”)

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

.end()

class ace.core.graphql.selection.Directive(name: str, args: Dict[str, Any] | None = None)

Bases: object

Represents 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)

build() → str

Build the directive string.

class ace.core.graphql.selection.Include(variable: str)

Bases: Directive

Shorthand for @include(if: $variable) directive.

__init__(variable: str)

build() → str

Build the directive string.

class ace.core.graphql.selection.Skip(variable: str)

Bases: Directive

Shorthand for @skip(if: $variable) directive.

__init__(variable: str)

build() → str

Build the directive string.

class ace.core.graphql.selection.SelectionSet(*fields: str, nested: Dict[str, SelectionSet] | None = None)

Bases: object

Represents 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)

Initialize a SelectionSet.

Parameters:

• *fields – Scalar field names to select

• nested – Dictionary of nested field name -> SelectionSet

add_field(field: str) → SelectionSet

Add a scalar field to the selection.

add_nested(name: str, selection: SelectionSet) → SelectionSet

Add a nested selection.

merge(other: SelectionSet) → SelectionSet

Merge another SelectionSet into this one.

Parameters:

other – SelectionSet to merge

Returns:

Self for chaining

build(indent: int = 0) → str

Build the selection set string.

Parameters:

indent – Current indentation level (for formatting)

Returns:

GraphQL selection set string

class ace.core.graphql.selection.SelectionBuilder(parent: OperationBuilder | None = None, field_name: str | None = None, args: Dict[str, Any] | None = None)

Bases: object

Builder for constructing selection sets with a fluent API.

This is used internally by OperationBuilder but can also be used standalone.

Supports directives on nested fields:

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

.include_if(“$includeMetadata”) .select(“entityType”)

.end()

__init__(parent: OperationBuilder | None = None, field_name: str | None = None, args: Dict[str, Any] | None = None)

Initialize a SelectionBuilder.

Parameters:

• parent – Parent builder (for .end() navigation)

• field_name – Name of the field this selection is for

• args – Arguments for this field (if it’s a nested operation)

select(*fields: str) → SelectionBuilder

Add scalar fields to the selection.

Parameters:

*fields – Field names to select

Returns:

Self for chaining

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

use(selection: SelectionSet) → SelectionBuilder

Apply a predefined SelectionSet to this builder.

Parameters:

selection – SelectionSet to apply

Returns:

Self for chaining

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()

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()

end() → SelectionBuilder | OperationBuilder

Return to the parent builder.

Returns:

Parent builder for continued chaining

build() → str

Build the selection set string.

Returns:

GraphQL selection set string (without outer braces)

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