grpcio/GRPCIO_USER_GUIDE.txt

================================================================================
  GRPCIO - USER GUIDE (Android Python STB) - Generated by RIMI
================================================================================

Package: grpcio 1.83.1 (latest stable on PyPI at build time)
Wheel tags: cp312-cp312-android_24_x86_64 / cp312-cp312-android_24_arm64_v8a
Runtime dep: typing_extensions~=4.12 (pure Python, own package - install it too)
Requires-Python: >=3.10 (app runs Python 3.12)

WHAT IT IS
-----------
gRPC is an HTTP/2-based RPC framework. The `grpc` package lets you build
clients and servers with unary and streaming calls, sync (`grpc`) and
async (`grpc.aio`) APIs, channels, interceptors, compression, and
TLS credentials. This wheel bundles the full upstream C++ core
(gRPC core, abseil, BoringSSL, c-ares, re2, upb, zlib) statically inside
one self-contained native extension, built from the official PyPI sdist
with the Android NDK (API 24). No extra native libraries are needed.

INSTALL
-------
1. Install this wheel (STANDALONE) with the app PipManager.
2. Install the matching pure-Python `typing_extensions` wheel (shipped
   alongside in STANDALONE) if it is not already installed.
3. `import grpc` - no setup, no preload, no environment variables.

QUICK START (loopback echo, no protobuf, no external network)
--------------------------------------------------------------
>>> from concurrent import futures
>>> import grpc
>>> def echo(request, context):
...     return b'echo:' + request
>>> h = grpc.unary_unary_rpc_method_handler(
...     echo, request_deserializer=lambda b: b,
...     response_serializer=lambda b: b)
>>> server = grpc.server(futures.ThreadPoolExecutor(max_workers=2))
>>> server.add_generic_rpc_handlers(
...     (grpc.method_handlers_generic_handler('test.Test', {'Echo': h}),))
>>> port = server.add_insecure_port('127.0.0.1:0')
>>> server.start()
>>> ch = grpc.insecure_channel('127.0.0.1:%d' % port)
>>> grpc.channel_ready_future(ch).result(timeout=15)
>>> ch.unary_unary('/test.Test/Echo')(b'ping', timeout=15)
b'echo:ping'
>>> ch.close(); server.stop(None)

For real services, generate stubs with `grpcio-tools` on your PC
(`python -m grpc_tools.protoc`) and copy the generated *_pb2.py files
to the device; this wheel then serves them at runtime.

ANDROID NOTES
-------------
- Loopback TCP (127.0.0.1) is used for local client+server in one process;
  no internet permission or external network is required for that.
- TLS roots: `grpc/_cython/_credentials/roots.pem` is bundled (same as
  upstream wheels) and used by default SSL credentials.
- Fork support is compiled in (GRPC_ENABLE_FORK_SUPPORT); on Android,
  prefer threads (as above) over os.fork().
- c-ares uses the vendored Android DNS config (bionic has no
  getservbyport_r); async name resolution works via the platform resolver.
- The extension links the app's libc++_shared and librimi (provided by
  the app, like all native packages) - nothing for you to install.

TESTED ON DEVICE (Test_Grpcio.py - ALL PASSED)
----------------------------------------------
1. import grpc + native cygrpc extension
2. grpc version 1.83.1
3. typing_extensions present
4. insecure_channel creation (no traffic)
5. loopback server bind on 127.0.0.1
6. channel ready on loopback
7. unary echo roundtrip b'ping' -> b'echo:ping'
8. second unary echo roundtrip (channel reuse)
9. StatusCode API surface

Run it from the app Scripts folder; exit code 0 means ALL PASSED
(network-restricted sandbox steps report SKIP instead of FAIL).

================================================================================
  Generated by RIMI
================================================================================