diff --git a/reference-doc-builder/src/main/java/bisq/apidoc/markdown/CodeExamples.java b/reference-doc-builder/src/main/java/bisq/apidoc/markdown/CodeExamples.java index 68c25ac..050b854 100644 --- a/reference-doc-builder/src/main/java/bisq/apidoc/markdown/CodeExamples.java +++ b/reference-doc-builder/src/main/java/bisq/apidoc/markdown/CodeExamples.java @@ -39,7 +39,7 @@ public class CodeExamples { // TODO Is hard-coding paths to example source files OK? private static final String CLI_EXAMPLES_DIR = "cli-examples"; private static final String JAVA_EXAMPLES_DIR = "java-examples/src/main/java/bisq/rpccalls"; - private static final String PYTHON_EXAMPLES_DIR = "python-examples/python_examples/bisq/rpccalls"; + private static final String PYTHON_EXAMPLES_DIR = "python-examples/bisq/rpccalls"; private static final String START_SHELL_MD = "```shell"; private static final String START_JAVA_MD = "```java"; diff --git a/reference-doc-builder/src/main/resources/templates/examples-setup.md b/reference-doc-builder/src/main/resources/templates/examples-setup.md index 70a9f29..62f83be 100644 --- a/reference-doc-builder/src/main/resources/templates/examples-setup.md +++ b/reference-doc-builder/src/main/resources/templates/examples-setup.md @@ -73,61 +73,10 @@ Running Python examples requires: - Generating protobuf and gRPC service stubs using the `protoc` compiler, with two additional Python protobuf and grpc plugins. -Instructions for generating the Bisq API Python stubs follow. +You can download the Bisq protobuf (.proto) files by running: -### Install python plugins for protoc compiler + `proto-downloader/download-bisq-protos.sh` - `$ python -m pip install grpcio grpcio-tools`
- `$ pip3 install mypy-protobuf` +You can build Python .proto stubs, install Python example dependencies, and package the examples by running: -### Download the Bisq .proto files to your Python project - -If your Python scripts are located in a directory named `my-api-scripts`, open a terminal in that directory and -download the Bisq .proto files to a directory named `my-api-scripts/proto`: - - `$ export PROTO_PATH="proto"`
- `$ curl -o $PROTO_PATH/pb.proto https://raw.githubusercontent.com/bisq-network/bisq/master/proto/src/main/proto/pb.proto`
- `$ curl -o $PROTO_PATH/grpc.proto https://raw.githubusercontent.com/bisq-network/bisq/master/proto/src/main/proto/grpc.proto` - -### Generate Bisq API gRPC Python stubs - -The location of Python code generated from downloaded Bisq .proto files _must_ be `/bisq/api`, or -this document's example Python scripts will not be able to import them at runtime. Put another way, if your Python -scripts are in a folder named `my-api-scripts`, the `protoc` compiler must generate Python stubs -in `my-api-scripts/bisq/api`. Each step of the setup is explained below. - -If - -- Python scripts are located in `my-api-scripts` -- Downloaded Bisq .proto files are located in `my-api-scripts/proto` -- A terminal is opened in directory `my-api-scripts` - -Generate API Python stubs in `my-api-scripts/bisq/api`, as follows: - - `$ export PROTO_PATH="proto"`
- `$ export PYTHON_PROTO_OUT_PATH="bisq/api"`
-
- `$ python3 -m grpc_tools.protoc \`
- `--proto_path=$PROTO_PATH \`
- `--python_out=$PYTHON_PROTO_OUT_PATH \`
- `--grpc_python_out=$PYTHON_PROTO_OUT_PATH $PROTO_PATH/*.proto`
-
- `$ protoc --proto_path=$PROTO_PATH --python_out=$PYTHON_PROTO_OUT_PATH $PROTO_PATH/*.proto`
-
- `# Hack two internal import statements in the generated Python code to prepend the bisq.api package name.`
- `# See why @ https://github.com/protocolbuffers/protobuf/issues/1491`
-
- `sed -i 's/import pb_pb2 as pb__pb2/import bisq.api.pb_pb2 as pb__pb2/g' $PYTHON_PROTO_OUT_PATH/grpc_pb2.py`
- `sed -i 's/import grpc_pb2 as grpc__pb2/import bisq.api.grpc_pb2 as grpc__pb2/g' $PYTHON_PROTO_OUT_PATH/grpc_pb2_grpc.py` - -Now you should be able to import the Bisq gRPC API stubs into scripts located in `my-api-scripts`, using the following -Python import statements: - - `import grpc`
- `import bisq.api.grpc_pb2 as bisq_messages`
- `import bisq.api.grpc_pb2_grpc as bisq_service` - -### _TODO Simplify these Python example setup sections..._ - -_if more experienced Python developers can demonstrate an easier, more flexible way of generating protobuf / grpc stubs -without having to manually hack internal import statements._ + `python-examples/run-setup.sh`