-
Notifications
You must be signed in to change notification settings - Fork 54
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
updated readme for SDK, fixed a link in the CLI readme
- Loading branch information
1 parent
2ff6d2d
commit a295aa7
Showing
2 changed files
with
48 additions
and
36 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -6,56 +6,68 @@ SingularityNET SDK for Python | |
|
|
||
| These instructions are for the development and use of the SingularityNET SDK for Python. | ||
|
|
||
| ### Usage | ||
| ### Core concepts | ||
|
|
||
| The SingularityNET SDK allows you to make calls to SingularityNET services programmatically from your application. | ||
| To communicate between clients and services, SingularityNET uses [gRPC](https://grpc.io/). | ||
| To handle payment of services, SingularityNET uses [Ethereum state channels](https://dev.singularitynet.io/docs/concepts/multi-party-escrow/). | ||
| The SingularityNET SDK abstracts and manages state channels with service providers on behalf of the user and handles authentication with the SingularityNET services. | ||
|
|
||
| The SingularityNET SDK allows you to import compiled client libraries for your service or services or choice and make calls to those services programmatically from your application by setting up state channels with the providers of those services and making gRPC calls to the SingularityNET daemons for those services by selecting a channel with sufficient funding and supplying the appropriate metadata for authentication. | ||
| ### Usage | ||
|
|
||
| Once you have installed the snet-sdk in your current environment and it's in your PYTHONPATH, you should import it and create an instance of the base sdk class: | ||
| To call a SingularityNET service, the user must be able to deposit funds (AGI tokens) to the [Multi-Party Escrow](https://dev.singularitynet.io/docs/concepts/multi-party-escrow/) Smart Contract. | ||
| To deposit these tokens or do any other transaction on the Ethereum blockchain, the user must possess an Ethereum identity with available Ether. | ||
|
|
||
| ```python | ||
| from snet_sdk import Snet | ||
| import config | ||
| snet = Snet(private_key=config.private_key) | ||
| ``` | ||
|
|
||
| Now, the instance of the sdk can be used to instantiate clients for SingularityNET services. To interact with those services, the sdk needs to be supplied the compiled client libraries and a reference to their path on your file system. | ||
|
|
||
| To generate the client libraries, you need the SingularityNET Command Line Interface, or CLI, which you can download from PyPi, see [https://github.com/singnet/snet-cli#installing-with-pip](https://github.com/singnet/snet-cli#installing-with-pip) | ||
| To interact with SingularityNET services, you must compile the appropriate client libraries for that service. | ||
| To generate the client libraries to use in your application, you need the SingularityNET Command Line Interface, or CLI, which you can download from PyPi, see [https://github.com/singnet/snet-cli#installing-with-pip](https://github.com/singnet/snet-cli/snet_cli#installing-with-pip) | ||
|
|
||
| Once you have the CLI installed, run the following command: | ||
| ```bash | ||
| snet sdk generate-client-library python <org_id> <service_id> | ||
| ``` | ||
|
|
||
| Optionally, you can specify an output path; otherwise it's going to be `./client_libraries/python/<org_id>/<service_id>` | ||
| Optionally, you can specify an output path; otherwise it's going to be `./client_libraries/python/<registry_address>/<org_id>/<service_id>`. | ||
| You should move or copy these generated files to the root of your project. | ||
|
|
||
| Now, by default the sdk is going to look for those client libraries in the `./grpc/<org_id>/<service_id>` in the directory of the main process of the module it's being imported by. | ||
|
|
||
| Once you have the generated client libraries in place, you can create an instance of a SingularityNET service client: | ||
| Once you have installed the snet-sdk in your current environment and it's in your PYTHONPATH, you should import it and create an instance of the base sdk class: | ||
|
|
||
| ```python | ||
| client = snet.client("<org_id>", "<service_id>") | ||
| from snet_sdk import SnetSDK | ||
| from config import config | ||
| snet = SnetSDK(config) | ||
| ``` | ||
|
|
||
| The client exposes the following properties and methods: | ||
| - All of the modules from the generated client library as `client.grpc.<module_name`. These are temporarily added to your PYTHONPATH and imported at runtime | ||
| - Functions to open, fund and extend state channels | ||
| - Functions to retrieve the list of state channels between you and the service provider from the blockchain | ||
| - Functions to get the updated state for a specific channel from the service provider, signed by yourself | ||
| - Functions to generate and sign the required metadata to make gRPC calls to the service daemon | ||
| The `config` parameter must be a Python dictionary. | ||
| See [config.py.sample](https://github.com/singnet/snet-code-examples/blob/master/python/client/config.py.sample) for a sample configuration file. | ||
|
|
||
| This is an example of how to make a call to a SingularityNET service in the `snet` organization with the `example-service` service_id using the base SDK and client instances created as shown before: | ||
| Now, the instance of the sdk can be used to create service client instances. To create a service client instance, it needs to be supplied with the client libraries that you compiled before. | ||
| Specifically, it needs the `Stub` object of the service you want to use from the compiled `_pb2_grpc.py` file of the client library. | ||
| Continuing from the previous code this is an example using `example-service` from the `snet` organization: | ||
|
|
||
| ```python | ||
| stub = client.grpc.example_service_pb2_grpc.CalculatorStub(client.grpc_channel) | ||
| request = calculator.grpc.example_service_pb2.Numbers(a=10, b=12) | ||
| result = stub.add(request) | ||
| print(result) | ||
| import example_service_pb2_grpc | ||
|
|
||
| org_id = "snet" | ||
| service_id = "example-service" | ||
|
|
||
| service_client = sdk.create_service_client(org_id, service_id, example_service_pb2_grpc.CalculatorStub) | ||
| ``` | ||
| If you have no open state channels with the service provider, you can create one by calling the following function: | ||
|
|
||
| The generated `service_client` instance can be used to call the methods exposed by the service. | ||
| To call these methods, a request object must be provided. Specifically, you should pick the appropriate request message type that is referenced in the stub object. | ||
| Continuing from the previous code this is an example using `example-service` from the `snet` organization: | ||
|
|
||
| ```python | ||
| client.open_channel() | ||
| import example_service_pb2 | ||
|
|
||
| request = example_service_pb2.Numbers(a=20, b=3) | ||
|
|
||
| result = service_client.service.mul(request) | ||
| print("Performing 20 * 3: {}".format(result)) # Performing 20 * 3: value: 60.0 | ||
| ``` | ||
| By default, this will create a channel with the shortest possible expiration date and the necessary amount to make 100 service calls. | ||
| Once an open channel is created and funded, the sdk will automatically find and use a funded, non-expired channel. | ||
|
|
||
| You can get this code example at [https://github.com/singnet/snet-code-examples/tree/python_client/python/client](https://github.com/singnet/snet-code-examples/tree/python_client/python/client) | ||
|
|
||
| For more information about gRPC and how to use it with Python, please see: | ||
| - [gRPC Basics - Python](https://grpc.io/docs/tutorials/basic/python.html) | ||
|
|
@@ -76,8 +88,8 @@ For more information about gRPC and how to use it with Python, please see: | |
|
|
||
| * Clone the git repository | ||
| ```bash | ||
| $ git clone [email protected]:singnet/snet-sdk-python.git | ||
| $ cd snet-sdk-python | ||
| $ git clone [email protected]:singnet/snet-cli.git | ||
| $ cd snet-cli/snet_sdk | ||
| ``` | ||
|
|
||
| * Install development/test blockchain dependencies | ||
|
|
@@ -93,9 +105,9 @@ $ pip install -e . | |
| ### Versioning | ||
|
|
||
| We use [SemVer](http://semver.org/) for versioning. For the versions available, see the | ||
| [tags on this repository](https://github.com/singnet/snet-sdk-python/tags). | ||
| [tags on this repository](https://github.com/singnet/snet-cli/tags). | ||
|
|
||
| ## License | ||
|
|
||
| This project is licensed under the MIT License - see the | ||
| [LICENSE](https://github.com/singnet/snet-sdk-python/blob/master/LICENSE) file for details. | ||
| [LICENSE](https://github.com/singnet/snet-cli/blob/master/snet_sdk/LICENSE) file for details. | ||