[ARVADOS] updated: 378080d4edc6fff9c5eb7edffe034ae77c7269e9
git at public.curoverse.com
git at public.curoverse.com
Thu Dec 19 15:53:30 EST 2013
Summary of changes:
doc/user/reference/sdk-python.textile | 127 +++++++++++++++++++++++++++++++++
sdk/python/arvados/__init__.py | 70 +++++++++++-------
2 files changed, 169 insertions(+), 28 deletions(-)
create mode 100644 doc/user/reference/sdk-python.textile
via 378080d4edc6fff9c5eb7edffe034ae77c7269e9 (commit)
via e56bea4b4ba13bd07ea5480b6b21804e368c8812 (commit)
from 0e140a472e787e6efa9a235bfdaa1e960e2aaa49 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
commit 378080d4edc6fff9c5eb7edffe034ae77c7269e9
Author: Tom Clegg <tom at clinicalfuture.com>
Date: Thu Dec 19 12:46:24 2013 -0800
Add Python SDK doc page. closes #1754
diff --git a/doc/user/reference/sdk-python.textile b/doc/user/reference/sdk-python.textile
new file mode 100644
index 0000000..fe824ac
--- /dev/null
+++ b/doc/user/reference/sdk-python.textile
@@ -0,0 +1,127 @@
+---
+layout: default
+navsection: userguide
+title: "Python SDK"
+navorder: 323
+---
+
+h1. Reference: Python SDK
+
+The Python SDK provides a generic set of wrappers so you can make API calls easily. It performs some validation before connecting to the API server: for example, it refuses to do an API call if a required parameter is missing.
+
+The library also includes some conveniences for use in Crunch scripts; see "Crunch utility libraries":crunch-utility-libraries.html for details.
+
+h3. Installation
+
+If you are logged in to an Arvados VM, the Python SDK should be installed.
+
+To use the Python SDK elsewhere, build and install the package using the arvados source tree.
+
+<notextile>
+<pre>
+$ <code class="userinput">git clone https://github.com/curoverse/arvados.git</code>
+$ <code class="userinput">cd arvados/sdk/python</code>
+$ <code class="userinput">sudo python setup.py install</code>
+</pre>
+</notextile>
+
+If the SDK is installed and your @ARVADOS_API_HOST@ and @ARVADOS_API_TOKEN@ environment variables are set up correctly (see "api-tokens":api-tokens.html for details), @import arvados@ should produce no errors:
+
+<notextile>
+<pre>$ <code class="userinput">python</code>
+Python 2.7.4 (default, Sep 26 2013, 03:20:26)
+[GCC 4.7.3] on linux2
+Type "help", "copyright", "credits" or "license" for more information.
+>>> <code class="userinput">import arvados</code>
+>>> <code class="userinput">arvados.api('v1')</code>
+<apiclient.discovery.Resource object at 0x233bb50>
+</pre>
+</notextile>
+
+h3. Examples
+
+Get the User object for the current user:
+
+<notextile>
+<pre><code class="userinput">current_user = arvados.api('v1').users().current().execute()
+</code></pre>
+</notextile>
+
+Get the UUID of an object that was retrieved using the SDK:
+
+<notextile>
+<pre><code class="userinput">my_uuid = current_user['uuid']
+</code></pre>
+</notextile>
+
+Retrieve an object by ID:
+
+<notextile>
+<pre><code class="userinput">some_user = arvados.api('v1').users().get(uuid=my_uuid).execute()
+</code></pre>
+</notextile>
+
+Create an object:
+
+<notextile>
+<pre><code class="userinput">test_link = arvados.api('v1').links().create(
+ body={'link_class':'test','name':'test'}).execute()
+</code></pre>
+</notextile>
+
+Update an object:
+
+<notextile>
+<pre><code class="userinput">arvados.api('v1').links().update(
+ uuid=test_link['uuid'],
+ body={'properties':{'foo':'bar'}}).execute()
+</code></pre>
+</notextile>
+
+Get a list of objects:
+
+<notextile>
+<pre><code class="userinput">repos = arvados.api('v1').repositories().list().execute()
+len(repos['items'])</code>
+2
+<code class="userinput">repos['items'][0]['uuid']</code>
+u'qr1hi-s0uqq-kg8cawglrf74bmw'
+</code></pre>
+</notextile>
+
+h3. Notes
+
+The general form of an API call is:
+
+<notextile>
+<pre><code class="userinput">arvados.api(<i>api_version</i>).<i>plural_resource_type</i>().<i>api_method</i>(<i>parameter</i>=<i>value</i>, ...).execute()
+</code></pre>
+</notextile>
+
+Many API methods accept a parameter whose name is the same as the resource type. For example, @links.create@ accepts a parameter called @link at . This parameter should be given as @body at .
+
+<notextile>
+<pre><code class="userinput">arvados.api('v1').links().create(
+ uuid=test_link['uuid'],
+ body={'properties':{'foo':'bar'}}).execute()
+</code></pre>
+</notextile>
+
+Currently, non-atom parameter values (hashes and lists) other than @body@ must be explicitly encoded using @json.dumps()@. (This will be fixed in a future release.)
+
+<notextile>
+<pre><code class="userinput">arvados.api('v1').links().list(
+ where=json.dumps({'link_class':'permission'})).execute()
+</code></pre>
+</notextile>
+
+One way to make API calls slightly less verbose is:
+
+<notextile>
+<pre><code class="userinput">arv = arvados.api('v1')
+j = arv.jobs().list().execute()
+</code></pre>
+</notextile>
+
+The SDK retrieves the list of API methods from the server at run time. Therefore, the set of available methods is determined by the server version rather than the SDK version.
+
commit e56bea4b4ba13bd07ea5480b6b21804e368c8812
Author: Tom Clegg <tom at clinicalfuture.com>
Date: Thu Dec 19 12:52:06 2013 -0800
Accept an API version argument to arvados.api(). refs #1772
diff --git a/sdk/python/arvados/__init__.py b/sdk/python/arvados/__init__.py
index 8d0ed0f..f3c7397 100644
--- a/sdk/python/arvados/__init__.py
+++ b/sdk/python/arvados/__init__.py
@@ -26,6 +26,8 @@ if 'ARVADOS_DEBUG' in os.environ:
EMPTY_BLOCK_LOCATOR = 'd41d8cd98f00b204e9800998ecf8427e+0'
+services = {}
+
class errors:
class SyntaxError(Exception):
pass
@@ -62,27 +64,9 @@ class CredentialsFromEnv(object):
http.request = types.MethodType(self.http_request, http)
return http
-url = ('https://%s:%s/discovery/v1/apis/'
- '{api}/{apiVersion}/rest' %
- (os.environ['ARVADOS_API_HOST'],
- os.environ.get('ARVADOS_API_PORT') or "443"))
-credentials = CredentialsFromEnv()
-
-# Use system's CA certificates (if we find them) instead of httplib2's
-ca_certs = '/etc/ssl/certs/ca-certificates.crt'
-if not os.path.exists(ca_certs):
- ca_certs = None # use httplib2 default
-
-http = httplib2.Http(ca_certs=ca_certs)
-http = credentials.authorize(http)
-if re.match(r'(?i)^(true|1|yes)$',
- os.environ.get('ARVADOS_API_HOST_INSECURE', '')):
- http.disable_ssl_certificate_validation=True
-service = build("arvados", "v1", http=http, discoveryServiceUrl=url)
-
def task_set_output(self,s):
- service.job_tasks().update(uuid=self['uuid'],
- body={
+ api('v1').job_tasks().update(uuid=self['uuid'],
+ body={
'output':s,
'success':True,
'progress':1.0
@@ -93,7 +77,7 @@ def current_task():
global _current_task
if _current_task:
return _current_task
- t = service.job_tasks().get(uuid=os.environ['TASK_UUID']).execute()
+ t = api('v1').job_tasks().get(uuid=os.environ['TASK_UUID']).execute()
t = UserDict.UserDict(t)
t.set_output = types.MethodType(task_set_output, t)
t.tmpdir = os.environ['TASK_WORK']
@@ -105,7 +89,7 @@ def current_job():
global _current_job
if _current_job:
return _current_job
- t = service.jobs().get(uuid=os.environ['JOB_UUID']).execute()
+ t = api('v1').jobs().get(uuid=os.environ['JOB_UUID']).execute()
t = UserDict.UserDict(t)
t.tmpdir = os.environ['JOB_WORK']
_current_job = t
@@ -114,8 +98,34 @@ def current_job():
def getjobparam(*args):
return current_job()['script_parameters'].get(*args)
-def api():
- return service
+def api(version=None):
+ global services
+ if not services.get(version):
+ apiVersion = version
+ if not version:
+ apiVersion = 'v1'
+ logging.info("Using default API version. " +
+ "Call arvados.api('%s') instead." %
+ apiVersion)
+ if 'ARVADOS_API_HOST' not in os.environ:
+ raise Exception("ARVADOS_API_HOST is not set. Aborting.")
+ url = ('https://%s/discovery/v1/apis/{api}/{apiVersion}/rest' %
+ os.environ['ARVADOS_API_HOST'])
+ credentials = CredentialsFromEnv()
+
+ # Use system's CA certificates (if we find them) instead of httplib2's
+ ca_certs = '/etc/ssl/certs/ca-certificates.crt'
+ if not os.path.exists(ca_certs):
+ ca_certs = None # use httplib2 default
+
+ http = httplib2.Http(ca_certs=ca_certs)
+ http = credentials.authorize(http)
+ if re.match(r'(?i)^(true|1|yes)$',
+ os.environ.get('ARVADOS_API_HOST_INSECURE', '')):
+ http.disable_ssl_certificate_validation=True
+ services[version] = build(
+ 'arvados', apiVersion, http=http, discoveryServiceUrl=url)
+ return services[version]
class JobTask(object):
def __init__(self, parameters=dict(), runtime_constraints=dict()):
@@ -139,9 +149,9 @@ class job_setup:
'input':task_input
}
}
- service.job_tasks().create(body=new_task_attrs).execute()
+ api('v1').job_tasks().create(body=new_task_attrs).execute()
if and_end_task:
- service.job_tasks().update(uuid=current_task()['uuid'],
+ api('v1').job_tasks().update(uuid=current_task()['uuid'],
body={'success':True}
).execute()
exit(0)
@@ -162,9 +172,9 @@ class job_setup:
'input':task_input
}
}
- service.job_tasks().create(body=new_task_attrs).execute()
+ api('v1').job_tasks().create(body=new_task_attrs).execute()
if and_end_task:
- service.job_tasks().update(uuid=current_task()['uuid'],
+ api('v1').job_tasks().update(uuid=current_task()['uuid'],
body={'success':True}
).execute()
exit(0)
@@ -1051,3 +1061,7 @@ class KeepClient(object):
return ''
with open(os.path.join(os.environ['KEEP_LOCAL_STORE'], r.group(0)), 'r') as f:
return f.read()
+
+# We really shouldn't do this but some clients still use
+# arvados.service.* directly instead of arvados.api().*
+service = api()
-----------------------------------------------------------------------
hooks/post-receive
--
More information about the arvados-commits
mailing list