doc/sdk/python/cookbook.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: sdk
   4 navmenu: Python
   5 title: Code cookbook
   6 ...
   7 {% comment %}
   8 Copyright (C) The Arvados Authors. All rights reserved.
   9
  10 SPDX-License-Identifier: CC-BY-SA-3.0
  11 {% endcomment %}
  12
  13 # "Cancel a container request":#cancel-a-container-request
  14 # "Cancel all container requests":#cancel-all-container-requests
  15 # "List completed container requests":#list-completed-container-requests
  16 # "Get input of a CWL workflow":#get-input-of-a-cwl-workflow
  17 # "Get output of a CWL workflow":#get-output-of-a-cwl-workflow
  18 # "Get state of a CWL workflow":#get-state-of-a-cwl-workflow
  19 # "List input of child requests":#list-input-of-child-requests
  20 # "List output of child requests":#list-output-of-child-requests
  21 # "List failed child requests":#list-failed-child-requests
  22 # "Get log of a child request":#get-log-of-a-child-request
  23 # "Create a collection sharing link":#sharing-link
  24 # "Combine two or more collections":#combine-two-or-more-collections
  25 # "Upload a file into a new collection":#upload-a-file-into-a-new-collection
  26 # "Download a file from a collection":#download-a-file-from-a-collection
  27 # "Copy files from a collection to a new collection":#copy-files-from-a-collection-to-a-new-collection
  28 # "Copy files from a collection to another collection":#copy-files-from-a-collection-to-another-collection
  29 # "Delete a file from an existing collection":#delete-a-file-from-an-existing-collection
  30 # "Listing records with paging":#listing-records-with-paging
  31 # "Querying the vocabulary definition":#querying-the-vocabulary-definition
  32 # "Translating between vocabulary identifiers and labels":#translating-between-vocabulary-identifiers-and-labels
  33 # "Create a Project":#create-a-project
  34
  35 h2(#cancel-a-container-request). Cancel a container request
  36
  37 {% codeblock as python %}
  38 import arvados
  39 arvados.api().container_requests().update(uuid=container_request_uuid, body={"priority": 0}).execute()
  40 {% endcodeblock %}
  41
  42 h2(#cancel-all-container-requests). Cancel all container requests
  43
  44 {% codeblock as python %}
  45 import arvados
  46 api = arvados.api()
  47 result = api.container_requests().list(filters=[["state", "=", "Committed"], ["priority", ">", "0"]]).execute()["items"]
  48 for container_request in result:
  49     api.container_requests().update(uuid=container_request["uuid"], body={"priority": 0}).execute()
  50 {% endcodeblock %}
  51
  52 h2(#list-completed-container-requests). List completed container requests
  53
  54 {% codeblock as python %}
  55 import arvados
  56 api = arvados.api()
  57 result = api.container_requests().list(filters=[["name", "like", name], ["state", "=", "Final"]]).execute()["items"]
  58 container_uuids = [cr["container_uuid"] for cr in result]
  59 containers = api.containers().list(filters=[["uuid", "in", container_uuids]]).execute()["items"]
  60 container_dict = {c["uuid"]: c for c in containers}
  61
  62 for container_request in result:
  63     container = container_dict[container_request["container_uuid"]]
  64     print("%s, %s, %s" % (container_request["uuid"], container_request["name"], "Success" if container["exit_code"] == 0 else "Failed"))
  65 {% endcodeblock %}
  66
  67 h2(#get-input-of-a-cwl-workflow). Get input of a CWL workflow
  68
  69 {% codeblock as python %}
  70 import arvados
  71 api = arvados.api()
  72 container_request_uuid="zzzzz-xvhdp-zzzzzzzzzzzzzzz"
  73 container_request = api.container_requests().get(uuid=container_request_uuid).execute()
  74 print(container_request["mounts"]["/var/lib/cwl/cwl.input.json"])
  75 {% endcodeblock %}
  76
  77 h2(#get-output-of-a-cwl-workflow). Get output of a CWL workflow
  78
  79 {% codeblock as python %}
  80 import arvados
  81 import arvados.collection
  82 api = arvados.api()
  83 container_request_uuid="zzzzz-xvhdp-zzzzzzzzzzzzzzz"
  84 container_request = api.container_requests().get(uuid=container_request_uuid).execute()
  85 collection = arvados.collection.CollectionReader(container_request["output_uuid"])
  86 print(collection.open("cwl.output.json").read())
  87 {% endcodeblock %}
  88
  89 h2(#get-state-of-a-cwl-workflow). Get state of a CWL workflow
  90
  91 {% codeblock as python %}
  92 import arvados
  93 def get_cr_state(cr_uuid):
  94     api = arvados.api()
  95     cr = api.container_requests().get(uuid=cr_uuid).execute()
  96     if cr['container_uuid'] is None:
  97         return cr['state']
  98     c = api.containers().get(uuid=cr['container_uuid']).execute()
  99     if cr['state'] == 'Final' and c['state'] != 'Complete':
 100         return 'Cancelled'
 101     elif c['state'] in ['Locked', 'Queued']:
 102         if c['priority'] == 0:
 103             return 'On hold'
 104         else:
 105             return 'Queued'
 106     elif c['state'] == 'Complete' and c['exit_code'] != 0:
 107         return 'Failed'
 108     elif c['state'] == 'Running':
 109         if c['runtime_status'].get('error', None):
 110             return 'Failing'
 111         elif c['runtime_status'].get('warning', None):
 112             return 'Warning'
 113     return c['state']
 114 container_request_uuid = 'zzzzz-xvhdp-zzzzzzzzzzzzzzz'
 115 print(get_cr_state(container_request_uuid))
 116 {% endcodeblock %}
 117
 118 h2(#list-input-of-child-requests). List input of child requests
 119
 120 {% codeblock as python %}
 121 import arvados
 122 api = arvados.api()
 123 parent_request_uuid = "zzzzz-xvhdp-zzzzzzzzzzzzzzz"
 124 namefilter = "bwa%"  # the "like" filter uses SQL pattern match syntax
 125 container_request = api.container_requests().get(uuid=parent_request_uuid).execute()
 126 parent_container_uuid = container_request["container_uuid"]
 127 child_requests = api.container_requests().list(filters=[
 128     ["requesting_container_uuid", "=", parent_container_uuid],
 129     ["name", "like", namefilter]]).execute()
 130 for c in child_requests["items"]:
 131     print("%s" % c["name"])
 132     for m in c["mounts"].values():
 133         if "portable_data_hash" in m:
 134             print("  %s" % m["portable_data_hash"])
 135 {% endcodeblock %}
 136
 137 h2(#list-output-of-child-requests). List output of child requests
 138
 139 {% codeblock as python %}
 140 import arvados
 141 api = arvados.api()
 142 parent_request_uuid = "zzzzz-xvhdp-zzzzzzzzzzzzzzz"
 143 namefilter = "bwa%"  # the "like" filter uses SQL pattern match syntax
 144 container_request = api.container_requests().get(uuid=parent_request_uuid).execute()
 145 parent_container_uuid = container_request["container_uuid"]
 146 child_requests = api.container_requests().list(filters=[
 147     ["requesting_container_uuid", "=", parent_container_uuid],
 148     ["name", "like", namefilter]]).execute()
 149 output_uuids = [c["output_uuid"] for c in child_requests["items"]]
 150 collections = api.collections().list(filters=[["uuid", "in", output_uuids]]).execute()
 151 uuid_to_pdh = {c["uuid"]: c["portable_data_hash"] for c in collections["items"]}
 152 for c in child_requests["items"]:
 153     print("%s -> %s" % (c["name"], uuid_to_pdh[c["output_uuid"]]))
 154 {% endcodeblock %}
 155
 156 h2(#list-failed-child-requests). List failed child requests
 157
 158 {% codeblock as python %}
 159 import arvados
 160 api = arvados.api()
 161 parent_request_uuid = "zzzzz-xvhdp-zzzzzzzzzzzzzzz"
 162 container_request = api.container_requests().get(uuid=parent_request_uuid).execute()
 163 parent_container_uuid = container_request["container_uuid"]
 164 child_requests = api.container_requests().list(filters=[
 165     ["requesting_container_uuid", "=", parent_container_uuid]], limit=1000).execute()
 166 child_containers = {c["container_uuid"]: c for c in child_requests["items"]}
 167 cancelled_child_containers = api.containers().list(filters=[
 168     ["exit_code", "!=", "0"],
 169     ["uuid", "in", list(child_containers.keys())]], limit=1000).execute()
 170 for c in cancelled_child_containers["items"]:
 171     print("%s (%s)" % (child_containers[c["uuid"]]["name"], child_containers[c["uuid"]]["uuid"]))
 172 {% endcodeblock %}
 173
 174 h2(#get-log-of-a-child-request). Get log of a child request
 175
 176 {% codeblock as python %}
 177 import arvados
 178 import arvados.collection
 179 api = arvados.api()
 180 container_request_uuid = "zzzzz-xvhdp-zzzzzzzzzzzzzzz"
 181 container_request = api.container_requests().get(uuid=container_request_uuid).execute()
 182 collection = arvados.collection.CollectionReader(container_request["log_uuid"])
 183 for c in collection:
 184     if isinstance(collection.find(c), arvados.arvfile.ArvadosFile):
 185         print(collection.open(c).read())
 186 {% endcodeblock %}
 187
 188 h2(#sharing_link). Create a collection sharing link
 189
 190 {% codeblock as python %}
 191 import arvados
 192 api = arvados.api()
 193 download="https://your.download.server"
 194 collection_uuid="zzzzz-4zz18-zzzzzzzzzzzzzzz"
 195 token = api.api_client_authorizations().create(body={"api_client_authorization":{"scopes": [
 196     "GET /arvados/v1/collections/%s" % collection_uuid,
 197     "GET /arvados/v1/collections/%s/" % collection_uuid,
 198     "GET /arvados/v1/keep_services/accessible"]}}).execute()
 199 print("%s/c=%s/t=%s/_/" % (download, collection_uuid, token["api_token"]))
 200 {% endcodeblock %}
 201
 202 h2(#combine-two-or-more-collections). Combine two or more collections
 203
 204 Note, if two collections have files of the same name, the contents will be concatenated in the resulting manifest.
 205
 206 {% codeblock as python %}
 207 import arvados
 208 import arvados.collection
 209 api = arvados.api()
 210 project_uuid = "zzzzz-j7d0g-zzzzzzzzzzzzzzz"
 211 collection_uuids = ["zzzzz-4zz18-aaaaaaaaaaaaaaa", "zzzzz-4zz18-bbbbbbbbbbbbbbb"]
 212 combined_manifest = ""
 213 for u in collection_uuids:
 214     c = api.collections().get(uuid=u).execute()
 215     combined_manifest += c["manifest_text"]
 216 newcol = arvados.collection.Collection(combined_manifest)
 217 newcol.save_new(name="My combined collection", owner_uuid=project_uuid)
 218 {% endcodeblock %}
 219
 220 h2(#upload-a-file-into-a-new-collection). Upload a file into a new collection
 221
 222 {% codeblock as python %}
 223 import arvados
 224 import arvados.collection
 225
 226 project_uuid = "zzzzz-j7d0g-zzzzzzzzzzzzzzz"
 227 collection_name = "My collection"
 228 filename = "file1.txt"
 229
 230 api = arvados.api()
 231 c = arvados.collection.Collection()
 232 with open(filename, "rb") as reader:
 233     with c.open(filename, "wb") as writer:
 234         content = reader.read(128*1024)
 235         while content:
 236             writer.write(content)
 237             content = reader.read(128*1024)
 238 c.save_new(name=collection_name, owner_uuid=project_uuid)
 239 print("Saved %s to %s" % (collection_name, c.manifest_locator()))
 240 {% endcodeblock %}
 241
 242 h2(#download-a-file-from-a-collection). Download a file from a collection
 243
 244 {% codeblock as python %}
 245 import arvados
 246 import arvados.collection
 247
 248 collection_uuid = "zzzzz-4zz18-zzzzzzzzzzzzzzz"
 249 filename = "file1.txt"
 250
 251 api = arvados.api()
 252 c = arvados.collection.CollectionReader(collection_uuid)
 253 with c.open(filename, "rb") as reader:
 254     with open(filename, "wb") as writer:
 255         content = reader.read(128*1024)
 256         while content:
 257             writer.write(content)
 258             content = reader.read(128*1024)
 259 print("Finished downloading %s" % filename)
 260 {% endcodeblock %}
 261
 262 h2(#copy-files-from-a-collection-to-a-new-collection). Copy files from a collection to a new collection
 263
 264 {% codeblock as python %}
 265 import arvados.collection
 266
 267 source_collection = "zzzzz-4zz18-zzzzzzzzzzzzzzz"
 268 target_project = "zzzzz-j7d0g-zzzzzzzzzzzzzzz"
 269 target_name = "Files copied from source_collection"
 270 files_to_copy = ["folder1/sample1/sample1_R1.fastq",
 271                  "folder1/sample2/sample2_R1.fastq"]
 272
 273 source = arvados.collection.CollectionReader(source_collection)
 274 target = arvados.collection.Collection()
 275
 276 for f in files_to_copy:
 277     target.copy(f, "", source_collection=source)
 278
 279 target.save_new(name=target_name, owner_uuid=target_project)
 280 print("Created collection %s" % target.manifest_locator())
 281 {% endcodeblock %}
 282
 283 h2(#copy-files-from-a-collection-to-another-collection). Copy files from a collection to another collection
 284
 285 {% codeblock as python %}
 286 import arvados.collection
 287
 288 source_collection = "zzzzz-4zz18-zzzzzzzzzzzzzzz"
 289 target_collection = "zzzzz-4zz18-aaaaaaaaaaaaaaa"
 290 files_to_copy = ["folder1/sample1/sample1_R1.fastq",
 291                  "folder1/sample2/sample2_R1.fastq"]
 292
 293 source = arvados.collection.CollectionReader(source_collection)
 294 target = arvados.collection.Collection(target_collection)
 295
 296 for f in files_to_copy:
 297     target.copy(f, "", source_collection=source)
 298
 299 target.save()
 300 {% endcodeblock %}
 301
 302 h2(#delete-a-file-from-an-existing-collection). Delete a file from an existing collection
 303
 304 {% codeblock as python %}
 305 import arvados
 306
 307 c = arvados.collection.Collection("zzzzz-4zz18-zzzzzzzzzzzzzzz")
 308 c.remove("file2.txt")
 309 c.save()
 310 {% endcodeblock %}
 311
 312 h2(#listing-records-with-paging). Listing records with paging
 313
 314 Use the @arvados.util.keyset_list_all@ helper method to iterate over all the records matching an optional filter.  This method handles paging internally and returns results incrementally using a Python iterator.  The first parameter of the method takes a @list@ method of an Arvados resource (@collections@, @container_requests@, etc).
 315
 316 {% codeblock as python %}
 317 import arvados.util
 318
 319 api = arvados.api()
 320 for c in arvados.util.keyset_list_all(api.collections().list, filters=[["name", "like", "%sample123%"]]):
 321     print("got collection " + c["uuid"])
 322 {% endcodeblock %}
 323
 324 h2(#querying-the-vocabulary-definition). Querying the vocabulary definition
 325
 326 The Python SDK provides facilities to interact with the "active metadata vocabulary":{{ site.baseurl }}/admin/metadata-vocabulary.html in the system. The developer can do key and value lookups in a case-insensitive manner:
 327
 328 {% codeblock as python %}
 329 from arvados import api, vocabulary
 330 voc = vocabulary.load_vocabulary(api('v1'))
 331
 332 [k.identifier for k in set(voc.key_aliases.values())]
 333 # Example output: ['IDTAGCOLORS', 'IDTAGFRUITS', 'IDTAGCOMMENT', 'IDTAGIMPORTANCES', 'IDTAGCATEGORIES', 'IDTAGSIZES', 'IDTAGANIMALS']
 334 voc['IDTAGSIZES'].preferred_label
 335 # Example output: 'Size'
 336 [v.preferred_label for v in set(voc['size'].value_aliases.values())]
 337 # Example output: ['S', 'M', 'L', 'XL', 'XS']
 338 voc['size']['s'].aliases
 339 # Example output: ['S', 'small']
 340 voc['size']['Small'].identifier
 341 # Example output: 'IDVALSIZES2'
 342 {% endcodeblock %}
 343
 344 h2(#translating-between-vocabulary-identifiers-and-labels). Translating between vocabulary identifiers and labels
 345
 346 Client software might need to present properties to the user in a human-readable form or take input from the user without requiring them to remember identifiers. For these cases, there're a couple of conversion methods that take a dictionary as input like this:
 347
 348 {% codeblock as python %}
 349 from arvados import api, vocabulary
 350 voc = vocabulary.load_vocabulary(api('v1'))
 351
 352 voc.convert_to_labels({'IDTAGIMPORTANCES': 'IDVALIMPORTANCES1'})
 353 # Example output: {'Importance': 'Critical'}
 354 voc.convert_to_identifiers({'creature': 'elephant'})
 355 # Example output: {'IDTAGANIMALS': 'IDVALANIMALS3'}
 356 {% endcodeblock %}
 357
 358 h2(#create-a-project). Create a Project
 359
 360 {% codeblock as python %}
 361 import arvados
 362
 363 parent_project_uuid = "zzzzz-j7d0g-zzzzzzzzzzzzzzz"
 364 project_name = "My project"
 365
 366 g = arvados.api().groups().create(body={
 367   "group": {
 368     "group_class": "project",
 369     "owner_uuid": parent_project_uuid,
 370     "name": project_name,
 371   }}).execute()
 372
 373 print("New project uuid is", g["uuid"])
 374 {% endcodeblock %}