This is an automated email from the ASF dual-hosted git repository. chaokunyang pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit ecf13a2b98c8068e8ac513d866cf8920fdf8ae88 Author: chaokunyang <[email protected]> AuthorDate: Wed Jun 17 06:04:00 2026 +0000 🔄 synced local 'docs/compiler/' with remote 'docs/compiler/' --- docs/compiler/compiler-guide.md | 20 ++++++++++++++------ docs/compiler/flatbuffers-idl.md | 7 ++++--- docs/compiler/generated-code.md | 16 +++++++++++++--- docs/compiler/index.md | 6 ++++-- docs/compiler/protobuf-idl.md | 17 +++++++++-------- docs/compiler/schema-idl.md | 4 +++- 6 files changed, 47 insertions(+), 23 deletions(-) diff --git a/docs/compiler/compiler-guide.md b/docs/compiler/compiler-guide.md index 85d5bace5f..0c5ebd4912 100644 --- a/docs/compiler/compiler-guide.md +++ b/docs/compiler/compiler-guide.md @@ -73,6 +73,7 @@ Compile options: | `--emit-fdl` | Emit translated FDL (for non-FDL inputs) | `false` | | `--emit-fdl-path` | Write translated FDL to this path (file or directory) | (stdout) | | `--grpc` | Generate gRPC service companions for supported outputs | `false` | +| `--grpc-python-mode=MODE` | Python gRPC mode: `async` or `sync` | `async` | | `--grpc-web` | Generate JavaScript gRPC-Web client companions | `false` | Schema-level file options are supported for language-specific generation choices. @@ -155,16 +156,23 @@ foryc compiler/examples/service.fdl --java_out=./generated/java --python_out=./g ``` The generated gRPC service code uses Fory to serialize request and response -payloads. Java output imports grpc-java APIs, Python output imports `grpc`, Go -output imports grpc-go, Rust output imports `tonic` and `bytes`, Scala output -imports grpc-java APIs, and Kotlin output imports grpc-java and grpc-kotlin APIs -and uses coroutine stubs. C# output imports `Grpc.Core.Api` types and can be -hosted with normal .NET gRPC packages such as `Grpc.AspNetCore` or called -through `Grpc.Net.Client`. JavaScript output imports `@grpc/grpc-js`. +payloads. Java output imports grpc-java APIs, Python output defaults to +`grpc.aio`, Go output imports grpc-go, Rust output imports `tonic` and `bytes`, +Scala output imports grpc-java APIs, and Kotlin output imports grpc-java and +grpc-kotlin APIs and uses coroutine stubs. C# output imports `Grpc.Core.Api` +types and can be hosted with normal .NET gRPC packages such as `Grpc.AspNetCore` +or called through `Grpc.Net.Client`. JavaScript output imports `@grpc/grpc-js`. Applications that compile or run those generated service files must provide their own gRPC dependencies. Fory packages do not add a hard gRPC dependency for this feature. +Generate synchronous Python gRPC companions for existing sync `grpcio` +applications with: + +```bash +foryc compiler/examples/service.fdl --python_out=./generated/python --grpc --grpc-python-mode=sync +``` + **Generate JavaScript gRPC-Web browser clients:** ```bash diff --git a/docs/compiler/flatbuffers-idl.md b/docs/compiler/flatbuffers-idl.md index abf6652189..89b3751531 100644 --- a/docs/compiler/flatbuffers-idl.md +++ b/docs/compiler/flatbuffers-idl.md @@ -144,9 +144,10 @@ foryc api.fbs --java_out=./generated/java --python_out=./generated/python --go_o Generated service code imports grpc APIs, so applications must provide grpc-java, grpc-kotlin, Scala grpc-java APIs, `grpcio`, grpc-go, Rust `tonic` and `bytes`, `@grpc/grpc-js`, or C# `Grpc.Core.Api` plus server/client dependencies when they -compile or run those files. Fory packages do not add gRPC as a hard dependency. -Use `--grpc-web` with JavaScript output to generate browser clients that import -`grpc-web`. +compile or run those files. Python companions use `grpc.aio` by default and can +be generated in sync mode with `--grpc-python-mode=sync`. Fory packages do not +add gRPC as a hard dependency. Use `--grpc-web` with JavaScript output to +generate browser clients that import `grpc-web`. ### Defaults and Metadata diff --git a/docs/compiler/generated-code.md b/docs/compiler/generated-code.md index 9180887bb8..1f52db67e3 100644 --- a/docs/compiler/generated-code.md +++ b/docs/compiler/generated-code.md @@ -373,9 +373,14 @@ restored = Person.from_bytes(data) When a schema contains services and the compiler is run with `--grpc`, Python generation emits a companion module named `<module>_grpc.py`. The module name is derived from the Fory package by replacing dots with underscores, or `generated` -when the schema has no package. +when the schema has no package. Python gRPC output defaults to `grpc.aio` +AsyncIO APIs. ```python +import grpc +import grpc.aio + + class AddressBookServiceStub: def __init__(self, channel): self.lookup = channel.unary_unary( @@ -386,8 +391,8 @@ class AddressBookServiceStub: class AddressBookServiceServicer: - def lookup(self, request, context): - raise NotImplementedError("Method not implemented!") + async def lookup(self, request, context): + await context.abort(grpc.StatusCode.UNIMPLEMENTED, "Method not implemented!") def add_servicer(servicer, server): ... @@ -400,6 +405,11 @@ companion module must install `grpcio`; `pyfory` does not add a hard gRPC dependency. The Python API uses snake_case method names while preserving the original IDL method names in the gRPC wire paths. +Generate synchronous Python `grpcio` companions with +`--grpc --grpc-python-mode=sync`. Sync mode keeps the same generated filename +and public names, but servicer methods use regular `def` methods and sync +`grpc.Channel` and `grpc.Server` instances. + ## Rust ### Output Layout diff --git a/docs/compiler/index.md b/docs/compiler/index.md index be81f5bfc2..da10b2cd16 100644 --- a/docs/compiler/index.md +++ b/docs/compiler/index.md @@ -99,8 +99,10 @@ The generated service code uses normal gRPC APIs, but request and response objects are serialized with Fory. Applications provide their own grpc-java, grpc-kotlin, Scala grpc-java APIs, `grpcio`, grpc-go, Rust `tonic` and `bytes`, or C# `Grpc.Core.Api` and hosting/client dependencies; Fory packages do not add -gRPC as a hard dependency. JavaScript Node.js companions use `@grpc/grpc-js`; -browser clients are generated separately with `--grpc-web` and use `grpc-web`. +gRPC as a hard dependency. Python companions use `grpc.aio` by default and can +be generated in sync mode with `--grpc-python-mode=sync`. JavaScript Node.js +companions use `@grpc/grpc-js`; browser clients are generated separately with +`--grpc-web` and use `grpc-web`. ## Why Fory IDL? diff --git a/docs/compiler/protobuf-idl.md b/docs/compiler/protobuf-idl.md index 2c23602429..da5deba311 100644 --- a/docs/compiler/protobuf-idl.md +++ b/docs/compiler/protobuf-idl.md @@ -319,14 +319,15 @@ foryc api.proto --java_out=./generated/java --python_out=./generated/python --go ``` Generated Java service files compile against grpc-java, generated Python service -modules import `grpc`, generated Rust service files import `tonic` and `bytes`, -generated Go service files import grpc-go, generated JavaScript Node.js service -files import `@grpc/grpc-js`, -generated C# service files import `Grpc.Core.Api` types, generated Scala service -files compile against grpc-java, and generated Kotlin service files compile -against grpc-java and grpc-kotlin. Add those dependencies in your application -build; Fory packages do not add gRPC as a hard dependency. Use `--grpc-web` -with JavaScript output to generate browser clients that import `grpc-web`. +modules use `grpc.aio` by default, generated Rust service files import `tonic` +and `bytes`, generated Go service files import grpc-go, generated JavaScript +Node.js service files import `@grpc/grpc-js`, generated C# service files import +`Grpc.Core.Api` types, generated Scala service files compile against grpc-java, +and generated Kotlin service files compile against grpc-java and grpc-kotlin. +Add those dependencies in your application build; Fory packages do not add gRPC +as a hard dependency. Use `--grpc-python-mode=sync` for sync Python `grpcio` +companions. Use `--grpc-web` with JavaScript output to generate browser clients +that import `grpc-web`. Protobuf `oneof` fields are translated to Fory union fields inside request and response messages. Direct union RPC request or response types are not part of normal protobuf RPC syntax. diff --git a/docs/compiler/schema-idl.md b/docs/compiler/schema-idl.md index 28da5fa7d8..d2e12c989e 100644 --- a/docs/compiler/schema-idl.md +++ b/docs/compiler/schema-idl.md @@ -953,7 +953,9 @@ service PetDirectory { Applications that compile or run those companions provide their own gRPC dependency, such as grpc-java, grpc-kotlin, `grpcio`, grpc-go, Rust `tonic` and `bytes`, Scala grpc-java APIs, `@grpc/grpc-js`, `grpc-web`, or C# - `Grpc.Core.Api` plus a server or client package. + `Grpc.Core.Api` plus a server or client package. Python companions use + `grpc.aio` by default and can be generated in sync mode with + `--grpc-python-mode=sync`. **Grammar:** --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
