Package: pl-sandbox-api
Python API for WIMS' adm/raw moduleA Python 3 interface to communicate with asandboxInstallationThe latest stable version is available onPyPI:pipinstallsandbox-apior from sources:gitclonehttps://github.com/qcoumes/sandbox-apicdsandbox-api
python3setup.pyinstallUsageSandbox-api is pretty straightforward to use, you just need to import Sandbox and create
an instance with the url of the server :fromsandbox_apiimportSandboxsandbox=Sandbox("http://www.my-sandbox.com")Default request timeout is 60 seconds, use thetimeoutargument to override :sandbox=Sandbox("http://www.my-sandbox.com",timeout=2.5)SpecificationsYou can obtain the sandbox' host and container with the.specifications()method :>>>pprint.pp(sandbox.specifications()){'host':{'cpu':{'core':6,'logical':12,'freq_min':800.0,'freq_max':4700.0},'memory':{'ram':16723701760,'swap':9448923136,'storage':{'/dev/sda2':225603444736,'/dev/sda1':313942016,'/dev/sdc1':2000396288000}},'docker_version':'19.03.8-ce','sandbox_version':'3.0.0'},'container':{'count':20,'cpu':{'count':1,'period':1000,'shares':1024,'quota':0},'memory':{'ram':100000000,'swap':100000000,'storage':-1},'io':{'read_iops':{},'read_bps':{},'write_iops':{},'write_bps':{}},'process':-1,'working_dir_device':'/dev/sda2'}}Sandbox' UsageYou can obtain the sandbox' usage with the.usage()method :>>>pprint.pp(sandbox.usage()){'cpu':{'frequency':800.0504166666668,'usage':0.085,'usage_avg':[0.10416666666666667,0.09000000000000001,0.0775]},'memory':{'ram':5376819200,'swap':0,'storage':{'/dev/sda2':60275105792,'/dev/sda1':286720,'/dev/sdc1':1294363865088}},'io':{'read_iops':{'/dev/sdc1':0,'/dev/sda1':0,'/dev/sda2':0},'read_bps':{'/dev/sdc1':0,'/dev/sda1':0,'/dev/sda2':0},'write_iops':{'/dev/sdc1':0,'/dev/sda1':0,'/dev/sda2':0},'write_bps':{'/dev/sdc1':0,'/dev/sda1':0,'/dev/sda2':2048}},'network':{'sent_bytes':514,'received_bytes':526,'sent_packets':6,'received_packets':6},'process':326,'container':0}Downloading environments and filesYou can download files or environments through thedownload(uuid, path=None)method.uuidcorrespond to the ID of the environment on the sandbox.If only uuid is provided the whole environment will be downloading, if path is also provided, only
the file corresponding to path inside the environment will be downloaded.The downloaded object is returned as aio.BytesIO.Executing commandsUse theexecute(config, environ=None)method to execute commands on the sandbox. Config
must be a dictionary corresponding to a valid config as definedhere,
environ, if provided, must be a binary object implementing the.read()(I.G.file objectorio.BytesIO) at position 0 corresponding to a valid environment (again, more informationhere).The returned value is a dictionary corresponding to the response's json :You can check a config dictionnary by callingsandbox_api.utils.validate(config).>>>pprint.pp(sandbox.execute({"commands":["echo $((2+2))"]})){'status':0,'execution':[{'command':'echo $((2+2))','exit_code':0,'stdout':'4','stderr':'','time':0.28589797019958496}],'total_time':0.2871053218841553}Asynchronous APISince requests may take sometime before a response is available, an asynchronous interface is available
through the classASandbox:fromsandbox_apiimportASandboxsandbox=ASandbox("http://www.my-sandbox.com")ASandboxuseaiohttp, so timeout works
differently. The default total timeout is still 60 seconds, but you're able to set differents
timeout for different part of the process with the following arguments :total: The whole operation time including connection
establishment, request sending and response reading.connect: The time consists connection establishment for a new
connection or waiting for a free connection from a pool if
pool connection limits are exceeded.sock_connect: A timeout for connecting to a peer for a new
connection, not given from a pool.sock_read: The maximum allowed timeout for period between reading
a new data portion from a peer.sandbox=ASandbox("http://www.my-sandbox.com",total=2.5,connect=0.5)All parameters arefloats.Noneor0disables a particular timeout check, see theaiohttp's ClientTimeoutreference for defaults and additional details.To send requests,ASandboxuses a session that must be closed once done with the instance :sandbox=ASandbox("http://www.my-sandbox.com",total=2.5,connect=0.5)# do stuff with sandboxawaitsandbox.close()You can also use a context manager to automatically close the session once done :asyncwithASandbox("http://www.my-sandbox.com")assandbox:# do stuff with sandboxApart from the above, all the methods are the same thanSandboxbut are all declared with theasynckeyword and must be awaited :asyncwithASandbox("http://my-sandbox.com")assandbox:usage,specs,execution=awaitasyncio.gather(sandbox.usage(),sandbox.specifications(),sandbox.execute({"commands":["echo $((2+2))"]}))ExceptionsSince sandbox-api rely on HTTP, any response with a status code greater or equal to 300 will raise
a corresponding exceptionSanbox{STATUS}the response (arequests.Responseobject) received is
available in theresponseattribute of the exception.All of these exceptions inheritSandboxError.fromsandbox_apiimportSandboxError,Sandbox404try:file=s.download("872b604c-9cce-42e2-8888-9a0311f3a724","unknown")exceptSandbox404:print("'unknown' does not exists in environment '872b604c-9cce-42e2-8888-9a0311f3a724'")exceptSandboxErrorase:print("Sandbox responded with a '%d' status code"%e.response.status_code)Changelog1.1.0Sandbox.check()now return the size of the environment / file, 0 if not
found. It should not break backward compatibility because of how int are
evaluated as boolean.Added anasyncimplementation of the api using the classASandbox.asyncimplementation depends onaiohttp.Drop support for Python 3.5 & 3.61.0.1Update README.md1.0.0Now compatible with Sandbox 3.0.00.0.7Now use Github Action for testing and deployment to PyPI0.0.6Added methodSandbox451Added python 3.8 tp test matrix0.0.5Added methodcheck()toSandboxto check if an environment/file exists on the sandbox.0.0.4Added functionvalidate()to check a config dict insandbox_api.utils.0.0.3Added missing type hintscpuforSandbox0.0.2Added type hints forSandbox's attributes.0.0.1Initial release