From e94156e4f8e96bef62387910003d0f10339d8308 Mon Sep 17 00:00:00 2001 From: Brett Smith Date: Sun, 29 Jan 2023 13:01:53 -0500 Subject: [PATCH] 19792: Split collection recipes into separate cookbook sections Arvados-DCO-1.1-Signed-off-by: Brett Smith --- doc/sdk/python/cookbook.html.textile.liquid | 51 +++++++++++---------- 1 file changed, 27 insertions(+), 24 deletions(-) diff --git a/doc/sdk/python/cookbook.html.textile.liquid b/doc/sdk/python/cookbook.html.textile.liquid index f77bbfcd54..96bb121f2f 100644 --- a/doc/sdk/python/cookbook.html.textile.liquid +++ b/doc/sdk/python/cookbook.html.textile.liquid @@ -28,9 +28,12 @@ SPDX-License-Identifier: CC-BY-SA-3.0 # "Working with collections":#working-with-collections ## "Load and update an existing collection":#load-collection ## "Create and save a new collection":#create-collection -## "Read a file from a collection":#download-a-file-from-a-collection -## "Write a file to a collection":#upload-a-file-into-a-new-collection +## "Read a file from a collection":#read-a-file-from-a-collection +## "Download a file from a collection":#download-a-file-from-a-collection +## "Write a file to a collection":#write-a-file-into-a-new-collection +## "Upload a file to a collection":#upload-a-file-into-a-new-collection ## "Delete a file from a collection":#delete-a-file-from-an-existing-collection +## "Delete a directory from a collection recursively":#delete-a-directory-from-a-collection ## "Copy a file between collections":#copy-files-from-a-collection-to-another-collection ## "Combine two or more collections":#combine-two-or-more-collections ## "Create a collection sharing link":#sharing-link @@ -367,30 +370,29 @@ new_collection.save_new( ) {% endcodeblock %} -h3(#download-a-file-from-a-collection). Read a file from a collection +h3(#read-a-file-from-a-collection). Read a file from a collection -Once you have a @Collection@ object, the "@Collection.open@ method":{{ site.baseurl }}/sdk/python/arvados/collection.html#arvados.collection.RichCollectionBase.open lets you open files from a collection the same way you would open files from disk using Python's built-in @open@ function. It returns a file-like object that you can use in many of the same ways you would use any other file object. +Once you have a @Collection@ object, the "@Collection.open@ method":{{ site.baseurl }}/sdk/python/arvados/collection.html#arvados.collection.RichCollectionBase.open lets you open files from a collection the same way you would open files from disk using Python's built-in @open@ function. It returns a file-like object that you can use in many of the same ways you would use any other file object. This example prints all non-empty lines from @ExampleFile@ in your collection: {% codeblock as python %} import arvados.collection collection = arvados.collection.Collection(...) with collection.open('ExampleFile') as my_file: - ... -{% endcodeblock %} - -For a low-level example, this code prints all non-empty lines from @ExampleFile@ in your collection: - -{% codeblock as python %} -with collection.open('ExampleFile') as my_file: + # Read from my_file as desired. + # This example prints all non-empty lines from the file to stdout. for line in my_file: if not line.isspace(): print(line, end='') {% endcodeblock %} -For a higher-level example, you can pass the returned file object as a source for Python's standard "@shutil.copyfileobj@ function":https://docs.python.org/3/library/shutil.html#shutil.copyfileobj to download it. This code downloads @ExampleFile@ from your collection and saves it to the current working directory as @ExampleDownload@: +h3(#download-a-file-from-a-collection). Download a file from a collection + +Once you have a @Collection@ object, the "@Collection.open@ method":{{ site.baseurl }}/sdk/python/arvados/collection.html#arvados.collection.RichCollectionBase.open lets you open files from a collection the same way you would open files from disk using Python's built-in @open@ function. It returns a file-like object that you can use in many of the same ways you would use any other file object. You can pass it as a source to Python's standard "@shutil.copyfileobj@ function":https://docs.python.org/3/library/shutil.html#shutil.copyfileobj to download it. This code downloads @ExampleFile@ from your collection and saves it to the current working directory as @ExampleDownload@: {% codeblock as python %} +import arvados.collection import shutil +collection = arvados.collection.Collection(...) with ( collection.open('ExampleFile') as src_file, open('ExampleDownload', 'w') as dst_file, @@ -398,29 +400,28 @@ with ( shutil.copyfileobj(src_file, dst_file) {% endcodeblock %} -h3(#upload-a-file-into-a-new-collection). Write a file to a collection +h3(#write-a-file-into-a-new-collection). Write a file to a collection -Once you have a @Collection@ object, the "@Collection.open@ method":{{ site.baseurl }}/sdk/python/arvados/collection.html#arvados.collection.RichCollectionBase.open lets you open files from a collection the same way you would open files from disk using Python's built-in @open@ function. Pass a second mode argument like @'w'@ or @'a'@ to write a file in the collection. It returns a file-like object that you can use in many of the same ways you would use any other file object. +Once you have a @Collection@ object, the "@Collection.open@ method":{{ site.baseurl }}/sdk/python/arvados/collection.html#arvados.collection.RichCollectionBase.open lets you open files from a collection the same way you would open files from disk using Python's built-in @open@ function. Pass a second mode argument like @'w'@ or @'a'@ to write a file in the collection. It returns a file-like object that you can use in many of the same ways you would use any other file object. This example writes @Hello, Arvados!@ to a file named @ExampleHello@ in your collection: {% codeblock as python %} import arvados.collection collection = arvados.collection.Collection(...) with collection.open('ExampleFile', 'w') as my_file: - ... -{% endcodeblock %} - -For a low-level example, this code writes @Hello, world!@ to a file named @ExampleHello@ in your collection: - -{% codeblock as python %} -with collection.open('ExampleHello', 'w') as my_file: - print("Hello, world!", file=my_file) + # Write to my_file as desired. + # This example writes "Hello, world!" to the file. + print("Hello, Arvados!", file=my_file) collection.save_new(...) # or collection.save() to update an existing collection {% endcodeblock %} -For a higher-level example, you can pass the returned file object as a destination for Python's standard "@shutil.copyfileobj@ function":https://docs.python.org/3/library/shutil.html#shutil.copyfileobj to upload a file to a collection. This code reads @ExampleFile@ from the current working directory and uploads it into your collection as @ExampleUpload@: +h3(#upload-a-file-into-a-new-collection). Upload a file to a collection + +Once you have a @Collection@ object, the "@Collection.open@ method":{{ site.baseurl }}/sdk/python/arvados/collection.html#arvados.collection.RichCollectionBase.open lets you open files from a collection the same way you would open files from disk using Python's built-in @open@ function. Pass a second mode argument like @'w'@ or @'a'@ to write a file in the collection. It returns a file-like object that you can use in many of the same ways you would use any other file object. You can pass it as a destination to Python's standard "@shutil.copyfileobj@ function":https://docs.python.org/3/library/shutil.html#shutil.copyfileobj to upload data from a source file. This example reads @ExampleFile@ from the current working directory and uploads it into your collection as @ExampleUpload@: {% codeblock as python %} +import arvados.collection import shutil +collection = arvados.collection.Collection(...) with ( open('ExampleFile') as src_file, collection.open('ExampleUpload', 'w') as dst_file, @@ -440,7 +441,9 @@ collection.remove('ExamplePath') collection.save_new(...) # or collection.save() to update an existing collection {% endcodeblock %} -Like most Unix tools, @Collection.remove@ will raise an error if you try to remove a non-empty directory. Pass @recursive=True@ to delete everything under that directory from the collection: +h3(#delete-a-directory-from-a-collection). Delete a directory from a collection recursively + +Once you have a @Collection@ object, call the "@Collection.remove@ method":{{ site.baseurl }}/sdk/python/arvados/collection.html#arvados.collection.Collection.remove with a directory path and @recursive=True@ to delete everything under that directory from the collection. {% codeblock as python %} import arvados.collection -- 2.39.5