Skip to content

Commit 460006f

Browse files
opalczynskiopalczynski
committed
[LIB-837] Add missing docs about custom_sockets; move utils to another file, add possibility to recheck and update custom socket; add possibility to remove endpoints and dependencies;
1 parent 12cda74 commit 460006f

10 files changed

+509
-112
lines changed

‎docs/source/custom_sockets.rst‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
.. _custom-sockets:
2+
3+
=========================
4+
Custom Sockets in Syncano
5+
=========================
6+
7+
``Syncano`` provides possibility of creating the custom sockets. It means that there's a possibility
8+
to define a very specific endpoints in syncano application and use them as normal api calls.
9+
Currently custom sockets allow only one dependency - script. This mean that on the backend side
10+
each time the api is called - the script is executed and result from this script is returned as a result of the
11+
api call.
12+
13+
Creating a custom socket
14+
------------------------
15+
16+
There are two methods of creating the custom socket. First: use the helpers objects defined in Python Libray.
17+
Second: use the raw format - this is described below.
18+
19+
To create a custom socket follow the steps::
20+
21+
import syncano
22+
from syncano.models import CustomSocket, Endpoint, ScriptCall, ScriptDependency, RuntimeChoices
23+
from syncano.connection import Connection
24+
25+
custom_socket = CustomSocket(name='my_custom_socket') # this will create an object in place (do api call)
26+
27+
# define endpoints
28+
my_endpoint = Endpoint(name='my_endpoint') # again - no api call here
29+
my_endpoint.add_call(ScriptCall(name='custom_script'), methods=['GET'])
30+
my_endpoint.add_call(ScriptCall(name='another_custom_script'), methods=['POST'])
31+
32+
# explanation for the above lines:
33+
# The endpoint will be seen under `my_endpoint` name:
34+
# On this syncano api endpoint the above endpoint will be called (after custom socket creation)
35+
# <host>://<api_version>/instances/<instance_name>/endpoints/sockets/my_endpoint/
36+
# On this syncano api endpoint the details of the defined endpoint will be returned
37+
# <host>://<api_version>/instances/<instance_name>/sockets/my_custom_socket/endpoints/my_endpoint/
38+
# For the above endpoint - the two calls are defined, one uses GET method - the custom_script will be executed
39+
# there, second uses the POST method and then the another_custom_script will be called;
40+
# Currently only script are available for calls;
41+
42+
# After the creation of the endpoint, add them to custom_socket:
43+
custom_socket.add_endpoint(my_endpoint)
44+
45+
# define dependency now;
46+
# using a new script - defining new source code;
47+
custom_socket.add_dependency(
48+
ScriptDependency(
49+
Script(
50+
label='custom_script',
51+
runtime_name=RuntimeChoices.PYTHON_V5_0,
52+
source='print("custom_script")'
53+
)
54+
)
55+
)
56+
# using a existing script:
57+
another_custom_script = Script.please.get(id=2)
58+
custom_socket.add_dependency(
59+
ScriptDependency(
60+
another_custom_script
61+
)
62+
)
63+
64+
# now it is time to publish custom_socket;
65+
custom_socket.publish() # this will do an api call and will create script;
66+
67+
Some time is needed to setup the environment for this custom socket.
68+
There is possibility to check the custom socket status::
69+
70+
print(custom_socket.status)
71+
# and
72+
print(custom_socket.status_info)
73+
74+
# to reload object (read it again from syncano api) use:
75+
custom_socket.reload()
76+
77+
78+
79+
Updating the custom socket
80+
--------------------------
81+
82+
To update custom socket, use::
83+
84+
custom_socket = CustomSocket.please.get(name='my_custom_socket')
85+
86+
custom_socket.remove_endpoint(endpoint_name='my_endpoint')
87+
custom_socket.remove_dependency(dependency_name='custom_script')
88+
89+
# or add new:
90+
91+
custom_socket.add_endpoint(new_endpoint) # see above code for endpoint examples;
92+
custom_socket.add_dependency(new_dependency) # see above code for dependency examples;
93+
94+
custom_socket.update()
95+
96+
97+
Running the custom socket
98+
-------------------------
99+
100+
To run custom socket use::
101+
102+
# this will run the my_endpoint - and call the custom_script (method is GET);
103+
result = custom_socket.run(method='GET', endpoint_name='my_endpoint')
104+
105+
106+
Read all endpoints
107+
------------------
108+
109+
To get the all defined endpoints in custom socket run::
110+
111+
endpoints = custom_socket.get_endpoints()
112+
113+
for endpoint in endpoints:
114+
print(endpoint.name)
115+
print(endpoint.calls)
116+
117+
To run particular endpoint::
118+
119+
endpoint.run(method='GET')
120+
# or:
121+
endpoint.run(method='POST', data={'name': 'test_name'})
122+
123+
The data will be passed to the api call in the request body.
124+
125+
Custom sockets endpoints
126+
------------------------
127+
128+
Each custom socket is created from at least one endpoint. The endpoint is characterized by name and
129+
defined calls. Calls is characterized by name and methods. The name is a identification for dependency, eg.
130+
if it's equal to 'my_script' - the Script with label 'my_script' will be used (if exist and the source match),
131+
or new one will be created.
132+
There's a special wildcard method: `methods=['*']` - this mean that any request with
133+
any method will be executed in this endpoint.
134+
135+
To add endpoint to the custom_socket use::
136+
137+
my_endpoint = Endpoint(name='my_endpoint') # again - no api call here
138+
my_endpoint.add_call(ScriptCall(name='custom_script'), methods=['GET'])
139+
my_endpoint.add_call(ScriptCall(name='another_custom_script'), methods=['POST'])
140+
141+
custom_socket.add_endpoint(my_endpoint)
142+
143+
Custom socket dependency
144+
------------------------
145+
146+
Each custom socket has dependency - this is a meta information for endpoint: which resource
147+
should be used to return the api call results. The dependencies are bind to the endpoints call objects.
148+
Currently supported dependency in only script.
149+
150+
**Using new script**
151+
152+
::
153+
154+
custom_socket.add_dependency(
155+
ScriptDependency(
156+
Script(
157+
label='custom_script',
158+
runtime_name=RuntimeChoices.PYTHON_V5_0,
159+
source='print("custom_script")'
160+
)
161+
)
162+
)
163+
164+
165+
**Using defined script**
166+
167+
::
168+
169+
another_custom_script = Script.please.get(id=2)
170+
custom_socket.add_dependency(
171+
ScriptDependency(
172+
another_custom_script
173+
)
174+
)
175+
176+
177+
Custom socket recheck
178+
---------------------
179+
180+
The creation of the socket can fail - this happen, eg. when endpoint name is already taken by another
181+
custom socket. To check the statuses use::
182+
183+
print(custom_socket.status)
184+
print(custom_socket.status_info)
185+
186+
There is a possibility to re-check socket - this mean that if conditions are met - the socket will be
187+
`created` again and available to use - if not the error will be returned in status field.
188+
189+
Custom socket - raw format
190+
--------------------------
191+
192+
There is a possibility to create a custom socket from the raw JSON format::
193+
194+
CustomSocket.please.create(
195+
name='my_custom_socket_3',
196+
endpoints={
197+
"my_endpoint_3": {
198+
"calls":
199+
[
200+
{"type": "script", "name": "my_script_3", "methods": ["POST"]}
201+
]
202+
}
203+
},
204+
dependencies=[
205+
{
206+
"type": "script",
207+
"runtime_name": "python_library_v5.0",
208+
"name": "my_script_3",
209+
"source": "print(3)"
210+
}
211+
]
212+
)
213+
214+
The disadvantage of this method is that - the JSON internal structure must be known by developer.

‎docs/source/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Contents:
1919

2020
getting_started
2121
interacting
22+
custom_sockets
2223
refs/syncano
2324

2425

‎docs/source/refs/syncano.models.custom_sockets.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
syncano.models.custom_sockets
2+
=============================
3+
4+
.. automodule:: syncano.models.custom_sockets
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

‎docs/source/refs/syncano.models.custom_sockets_utils.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
syncano.models.custom_sockets_utils
2+
===================================
3+
4+
.. automodule:: syncano.models.custom_sockets_utils
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

‎docs/source/refs/syncano.models.geo.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
syncano.models.geo
2+
==================
3+
4+
.. automodule:: syncano.models.geo
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

‎docs/source/refs/syncano.models.hosting.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
syncano.models.hosting
2+
======================
3+
4+
.. automodule:: syncano.models.hosting
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

‎syncano/models/base.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,5 @@
1313
from .backups import * # NOQA
1414
from .hosting import * # NOQA
1515
from .data_views import DataEndpoint as EndpointData # NOQA
16-
from .custom_sockets import * # NOQA
16+
from .custom_sockets import * # NOQA
17+
from .custom_sockets_utils import Endpoint, ScriptCall, ScriptDependency # NOQA

0 commit comments

Comments
 (0)