gRPC schema

Fetch the protobuf schema of the Synthient gRPC API.

The synthient.grpcschema module fetches the protobuf schema of the Synthient gRPC API using gRPC server reflection. It needs the grpc extra, and importing it without the extra raises ImportError.

from synthient import grpcschema

fetch

Connects to a Synthient gRPC endpoint and uses server reflection to fetch the protobuf files that define symbols, along with all of their imports.

def fetch(
    api_key: str | None = None,
    *,
    endpoint: str = DEFAULT_ENDPOINT,
    plaintext: bool = False,
    symbols: Iterable[str] = (),
    timeout: float | None = 30.0,
) -> Schema

Name
api_key
Type
str | None
Description
Sent as x-api-key metadata when it is not empty. None reads the SYNTHIENT_API_KEY environment variable. Unlike Client, a missing key is not an error, but a key that is not a string raises TypeError.
Name
endpoint
Type
str
Description
The server as host:port, a bare host (port 443 is assumed), or a grpc:// or https:// URL. The default is DEFAULT_ENDPOINT.
Name
plaintext
Type
bool
Description
Disables TLS, for local development servers.
Name
symbols
Type
Iterable[str]
Description
Fully qualified service or message names to resolve. Surrounding whitespace is trimmed and duplicates are dropped. Empty resolves every service the server lists, except gRPC reflection itself.
Name
timeout
Type
float | None
Description
Seconds allowed for the whole fetch, or None for no limit.

from synthient import grpcschema

try:
    schema = grpcschema.fetch()
except grpcschema.SchemaError as error:
    explanation = grpcschema.explain(error)
    raise SystemExit(f"{explanation} {error}" if explanation else str(error)) from error

for file in schema.descriptor_set.file:
    print(file.name, file.package)

Errors: It raises SchemaError if reflection fails, ValueError if the endpoint or API key is invalid, and TypeError if the API key is not a string.

Schema

The protobuf schema returned by fetch, as a frozen dataclass.

Name
endpoint
Type
str
Description
The normalized address that was queried.
Name
symbols
Type
list[str]
Description
The service or message names that were resolved.
Name
descriptor_set
Type
FileDescriptorSet
Description
The resolved files in dependency order, each file after the files it imports. FileDescriptorSet comes from google.protobuf.descriptor_pb2.

SchemaError

A subclass of SynthientError raised when fetching the schema failed.

Name
code
Type
grpc.StatusCode | None
Description
The gRPC status code, or None when the failure was not a gRPC status.

explain

Returns a human-readable explanation of a common SchemaError raised by fetch, or "" if it has none.

def explain(error: BaseException) -> str

gRPC code	Explanation
`UNAUTHENTICATED`	Missing or invalid API key.
`PERMISSION_DENIED`	This API key does not have permission to inspect gRPC schemas.
`NOT_FOUND`	No protobuf schema found for the requested symbol. Fetch without symbols to list the available services.
`UNIMPLEMENTED`	The gRPC endpoint does not expose server reflection.
`UNAVAILABLE`	Could not reach the gRPC endpoint. Check the address, network access, and TLS settings.
`DEADLINE_EXCEEDED`	Timed out reading protobuf schemas from gRPC reflection. Use a longer timeout.

Constants

Name
DEFAULT_ENDPOINT
Type
str
Description
"grpc.synthient.com:443", the address of the Synthient gRPC API.