From 6ae95e0f9c936ef857b853d847b1d5a7a36bcae5 Mon Sep 17 00:00:00 2001 From: izzy lyseggen Date: Mon, 7 Dec 2020 10:52:57 +0000 Subject: [PATCH 1/3] docs: wip add some code samples --- README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/README.md b/README.md index 98e7edf..4b49483 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,74 @@ venv\Scripts\activate pip install -r requirements.txt ``` +## Overview of functionality + +Create a client and authenticate + +```py +from speckle.api.client import SpeckleClient +from speckle.api.credentials import get_default_account, get_local_accounts + +all_accounts = get_local_accounts() # get back a list +account = get_default_account() + +client = SpeckleClient(host="localhost:3000", use_ssl=False) +# client = SpeckleClinet(host="yourserver.com") or whatever your host is + +client.authenticate(account.token) +``` + +streams + +```py +# get your streams +stream_list = client.stream.list() + +# search your streams +results = client.user.search("mech") + +# create a stream +new_stream_id = client.stream.create(name="a shiny new stream") + +# get a stream +new_stream = client.stream.get(id=new_stream_id) +``` + +commits + +```py + +``` + +objects + +```py + +``` + +serialisation + +```py +detached_base = Base() +detached_base.name = "this will get detached" + +base_obj = Base() +base_obj.name = "my base" +base_obj["@nested"] = detached_base + +serializer = BaseObjectSerializer() +hash, obj_dict = serializer.traverse_base(base_obj) +``` + +transports + +```py +transport = MemoryTransport() + +hash = operations.send(base=base_obj, transports=[transport]) + +``` + ## Contributing Please make sure you read the [contribution guidelines](.github/CONTRIBUTING.md) for an overview of the best practices we try to follow. From e92562ccf3054673ea9e6b43c221b6b16533e370 Mon Sep 17 00:00:00 2001 From: izzy lyseggen Date: Mon, 7 Dec 2020 11:35:21 +0000 Subject: [PATCH 2/3] docs: more samples and text descriptions --- README.md | 42 +++++++++++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 4b49483..eaf436e 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ pip install -r requirements.txt ## Overview of functionality -Create a client and authenticate +The `SpeckleClient` is the entry point for interacting with the GraphQL API. You'll need to have a running server to use this. ```py from speckle.api.client import SpeckleClient @@ -54,16 +54,17 @@ new_stream = client.stream.get(id=new_stream_id) commits ```py +# get list of commits +commits = client.commit.get_list("stream id here") +# get a specific commit +commit = client.commit.get("stream id", "commit id") + +# create a commit +commit_id = client.commit.create("stream id", "object id", "this is a commit message to describe the commit") ``` -objects - -```py - -``` - -serialisation +The `BaseObjectSerializer` is used for decomposing and serializing `Base` objects so they can be sent / received to the server. You can use it directly to get the id (hash) and a serializable object representation of the decomposed `Base`. ```py detached_base = Base() @@ -77,13 +78,36 @@ serializer = BaseObjectSerializer() hash, obj_dict = serializer.traverse_base(base_obj) ``` -transports +If you use the `operations`, you will not need to interact with the serializer directly as this will be taken care of for you. You will just need to provide a transport to indicate where the objects should be sent / received from. At the moment, just the `MemoryTransport` is fully functional. ```py transport = MemoryTransport() +# this serialises the object and sends it to the transport hash = operations.send(base=base_obj, transports=[transport]) +# if the object had detached objects, you can see these as well +saved_objects = transport.objects # a dict with the obj hash as the key + +# this receives and object from the given transport, deserialises it, and recomposes it into a base object +received_base = operations.receive(obj_id=hash, remote_transport=transport) +``` + +You can also use the GraphQL API to send and receive objects. + +```py +# create a test base object +test_base = Base() +test_base.testing = "a test base obj" + +# run it through the serialiser +s = BaseObjectSerializer() +hash, obj = s.traverse_base(test_base) + +# send it to the server +objCreate = client.object.create(stream_id="stream id", objects=[obj]) + +received_base = client.object.get(hash) ``` ## Contributing From 0dca458a0ae535b57a9b59a7757ba3343e88d89a Mon Sep 17 00:00:00 2001 From: izzy lyseggen Date: Mon, 7 Dec 2020 11:42:24 +0000 Subject: [PATCH 3/3] docs: some more comments --- README.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index eaf436e..028d8a0 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ client = SpeckleClient(host="localhost:3000", use_ssl=False) client.authenticate(account.token) ``` -streams +Interacting with streams is meant to be intuitive and evocative of PySpeckle 1.0 ```py # get your streams @@ -51,7 +51,7 @@ new_stream_id = client.stream.create(name="a shiny new stream") new_stream = client.stream.get(id=new_stream_id) ``` -commits +New in 2.0: commits! Here are some basic commit interactions. ```py # get list of commits @@ -62,6 +62,9 @@ commit = client.commit.get("stream id", "commit id") # create a commit commit_id = client.commit.create("stream id", "object id", "this is a commit message to describe the commit") + +# delete a commit +deleted = client.commit.delete("stream id", "commit id") ``` The `BaseObjectSerializer` is used for decomposing and serializing `Base` objects so they can be sent / received to the server. You can use it directly to get the id (hash) and a serializable object representation of the decomposed `Base`. @@ -110,6 +113,8 @@ objCreate = client.object.create(stream_id="stream id", objects=[obj]) received_base = client.object.get(hash) ``` +This doc is not complete - there's more to see so have a dive into the code and play around! Please feel free to provide feedback, submit issues, or discuss new features ✨ + ## Contributing Please make sure you read the [contribution guidelines](.github/CONTRIBUTING.md) for an overview of the best practices we try to follow.