# gRPC schema

Fetch the protobuf schema of the Synthient gRPC API.

The `synthient.grpcschema` module fetches the protobuf schema of the Synthient [gRPC API](https://docs.synthient.com/grpc) using gRPC server reflection. It needs the `grpc` extra, and importing it without the extra raises `ImportError`.

```python
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.

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

- `api_key` `str | None` — 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`.
- `endpoint` `str` — The server as `host:port`, a bare host (port 443 is assumed), or a `grpc://` or `https://` URL. The default is `DEFAULT_ENDPOINT`.
- `plaintext` `bool` — Disables TLS, for local development servers.
- `symbols` `Iterable[str]` — 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.
- `timeout` `float | None` — Seconds allowed for the whole fetch, or `None` for no limit.

```python
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.

- `endpoint` `str` — The normalized address that was queried.
- `symbols` `list[str]` — The service or message names that were resolved.
- `descriptor_set` `FileDescriptorSet` — 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.

- `code` `grpc.StatusCode | None` — 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.

```python
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

- `DEFAULT_ENDPOINT` `str` — `"grpc.synthient.com:443"`, the address of the Synthient gRPC API.