New example doc format

changelog.d/20240717_125912_derek_globus_app_example_doc_updates.rst

@@ -0,0 +1,6 @@
+
+Documentation
+~~~~~~~~~~~~~
+
+- Added a new experimental "Updated Examples" section which rewrites and reorders
+  many examples to aid in discovery. (:pr:`NUMBER`)

docs/experimental/examples/endpoints_and_collections/create_guest_collection/index.rst

@@ -0,0 +1,9 @@
+
+Creating a Guest Collection
+===========================
+
+TODO
+
+.. literalinclude:: user_guest_collection.py
+    :caption: ``user_guest_collection.py`` [:download:`download <user_guest_collection.py>`]
+    :language: python

docs/experimental/examples/endpoints_and_collections/create_guest_collection/user_guest_collection.py

@@ -0,0 +1,45 @@
+import globus_sdk
+from globus_sdk.experimental.globus_app import UserApp
+
+# Tutorial Client ID - <replace this with your own client>
+NATIVE_CLIENT_ID = "61338d24-54d5-408f-a10d-66c06b59f6d2"
+USER_APP = UserApp("my-simple-transfer", client_id=NATIVE_CLIENT_ID)
+
+# Globus Tutorial Collection 1
+# https://app.globus.org/file-manager/collections/6c54cade-bde5-45c1-bdea-f4bd71dba2cc
+ENDPOINT_HOSTNAME = "https://b7a4f1.75bc.data.globus.org"
+MAPPED_COLLECTION_ID = "6c54cade-bde5-45c1-bdea-f4bd71dba2cc"
+
+
+def main():
+    gcs_client = globus_sdk.GCSClient(ENDPOINT_HOSTNAME, app=USER_APP)
+
+    # Comment out this line if the mapped collection is high assurance
+    attach_data_access_scope(gcs_client, MAPPED_COLLECTION_ID)
+
+    collection_request = globus_sdk.GuestCollectionDocument(
+        public=True,
+        collection_base_path="/",
+        display_name="example_guest_collection",
+        mapped_collection_id=MAPPED_COLLECTION_ID,
+    )
+
+    collection = gcs_client.create_collection(collection_request)
+    print(f"Created guest collection. Collection ID: {collection['id']}")
+
+
+def attach_data_access_scope(gcs_client, collection_id):
+    """Compose and attach a ``data_access`` scope for the supplied collection"""
+    endpoint_scopes = gcs_client.get_gcs_endpoint_scopes(gcs_client.endpoint_client_id)
+    collection_scopes = gcs_client.get_gcs_collection_scopes(collection_id)
+
+    manage_collections = globus_sdk.Scope(endpoint_scopes.manage_collections)
+    data_access = globus_sdk.Scope(collection_scopes.data_access, optional=True)
+
+    manage_collections.add_dependency(data_access)
+
+    gcs_client.add_app_scope(manage_collections)
+
+
+if __name__ == "__main__":
+    main()

docs/experimental/examples/endpoints_and_collections/identifying_entity_type.rst

@@ -0,0 +1,5 @@
+
+Identifying Entity Type
+=======================
+
+TODO

docs/experimental/examples/endpoints_and_collections/index.rst

@@ -0,0 +1,9 @@
+
+Endpoints and Collections
+=========================
+
+.. toctree::
+    :maxdepth: 1
+
+    identifying_entity_type
+    create_guest_collection/index

docs/experimental/examples/flows/create.rst

@@ -0,0 +1,5 @@
+
+Creating a Flow
+===============
+
+TODO

docs/experimental/examples/flows/delete.rst

@@ -0,0 +1,5 @@
+
+Deleting a Flow
+===============
+
+TODO

docs/experimental/examples/flows/index.rst

@@ -0,0 +1,11 @@
+
+Flows
+=====
+
+.. toctree::
+    :maxdepth: 1
+
+    create
+    list
+    run
+    delete

docs/experimental/examples/flows/list.rst

@@ -0,0 +1,5 @@
+
+Listing Flows
+=============
+
+TODO

docs/experimental/examples/flows/run.rst

@@ -0,0 +1,5 @@
+
+Running a Flow
+==============
+
+TODO

docs/experimental/examples/index.rst

@@ -0,0 +1,20 @@
+
+Updated Examples
+================
+
+This experimental doc restructures the existing `Globus SDK Examples <../../examples>`_
+section by:
+
+    * Grouping examples by common topic
+    * Consolidating & updating examples into a more uniform active format
+    * Updating references to leverage the latest SDK constructs (notably GlobusApp)
+
+
+.. toctree::
+    :maxdepth: 2
+
+    transferring_data/index
+    endpoints_and_collections/index
+    flows/index
+    projects/index
+    oauth2/index

docs/experimental/examples/oauth2/authorizers.rst

@@ -0,0 +1,5 @@
+
+Using Authorizers
+=================
+
+TODO

docs/experimental/examples/oauth2/customizing_token_storage.rst

@@ -0,0 +1,5 @@
+
+Customizing Token Storage
+=========================
+
+TODO

docs/experimental/examples/oauth2/globus_app.rst

@@ -0,0 +1,5 @@
+
+Using a Globus App
+==================
+
+TODO

docs/experimental/examples/oauth2/index.rst

@@ -0,0 +1,12 @@
+
+OAuth2 at Globus
+================
+
+.. toctree::
+    :maxdepth: 1
+
+    globus_app
+    authorizers
+    login_flows
+    customizing_token_storage
+    three_legged_oauth

docs/experimental/examples/oauth2/login_flows.rst

@@ -0,0 +1,5 @@
+
+Running Login Flows
+===================
+
+TODO

docs/experimental/examples/oauth2/three_legged_oauth.rst

@@ -0,0 +1,5 @@
+
+Performing Three Legged OAuth in Flask
+========================================
+
+TODO

docs/experimental/examples/projects/create.rst

@@ -0,0 +1,5 @@
+
+Creating a Project
+==================
+
+TODO

docs/experimental/examples/projects/delete.rst

@@ -0,0 +1,5 @@
+
+Deleting a Project
+==================
+
+TODO

docs/experimental/examples/projects/index.rst

@@ -0,0 +1,10 @@
+
+Auth Projects
+=============
+
+.. toctree::
+    :maxdepth: 1
+
+    create
+    list
+    delete

docs/experimental/examples/projects/list.rst

@@ -0,0 +1,5 @@
+
+Listing Projects
+================
+
+TODO

docs/experimental/examples/transferring_data/index.rst

@@ -0,0 +1,11 @@
+
+Transferring Data
+=================
+
+.. toctree::
+    :maxdepth: 1
+
+    submit_transfer/index
+    schedule_transfer/index
+    task_deadlines
+    recursive_ls

docs/experimental/examples/transferring_data/recursive_ls.rst

@@ -0,0 +1,5 @@
+
+Recursively Listing a Filesystem
+================================
+
+TODO

docs/experimental/examples/transferring_data/schedule_transfer/index.rst

@@ -0,0 +1,5 @@
+
+Scheduling a Transfer
+=====================
+
+TODO

docs/experimental/examples/transferring_data/submit_transfer/index.rst

@@ -0,0 +1,54 @@
+
+Initiating a Transfer
+=====================
+
+Moving data within the Globus Ecosystem can be performed by submitting a `Transfer Task`
+to the Globus Transfer service.
+
+The below example demonstrates how to submit that task using a ``TransferClient``.
+
+.. note::
+    The below example is for moving data between two publicly hosted "tutorial"
+    collections.
+    You should replace these collection ids and path values with your own collection
+    ids and paths.
+
+.. note::
+    Some collections require you to attach a "data_access" scope to your transfer
+    request. You should evaluate whether this is necessary for both your source and
+    destination collections and omit the ``transfer_client.add_app_data_access_scope``
+    calls as needed.
+
+    A collection requires "data_access" if it is (1) a mapped collection and (2) is
+    not high assurance.
+
+    If you're still not able to determine, an alternative reactive script is included
+    below.
+
+.. literalinclude:: submit_transfer.py
+    :caption: ``submit_transfer.py`` [:download:`download <submit_transfer.py>`]
+    :language: python
+
+
+Reactively solving ConsentRequired errors
+------------------------------------------
+
+Some collections require you to attach a "data_access" scope to your transfer
+request.
+
+This can be typically be done proactively: if you know which collections you or your
+users will interacting with, you can evaluate whether they require this scope (they are
+non-High Assurance mapped collections), and attach it through the client if so.
+
+Sometimes however you do not know in advance the full range of collections that your
+script will be interacting with. This script demonstrates how to reactively solve the
+``ConsentRequired`` errors which are raised when a collection requires a "data_access"
+scope but the client did not attach one.
+
+.. note::
+    Given that this script is reactive, it can involve two user login interactions
+    where the above script only involves one.
+
+.. literalinclude:: submit_transfer_reactive_consent_required.py
+    :caption: ``submit_transfer_reactive_consent_required.py`` [:download:`download <submit_transfer_reactive_consent_required.py>`]
+    :language: python

docs/experimental/examples/transferring_data/submit_transfer/submit_transfer.py

@@ -0,0 +1,38 @@
+import globus_sdk
+from globus_sdk.experimental.globus_app import UserApp
+
+# Tutorial Client ID - <replace this with your own client>
+NATIVE_CLIENT_ID = "61338d24-54d5-408f-a10d-66c06b59f6d2"
+USER_APP = UserApp("my-simple-transfer", client_id=NATIVE_CLIENT_ID)
+
+# Globus Tutorial Collection 1
+# https://app.globus.org/file-manager/collections/6c54cade-bde5-45c1-bdea-f4bd71dba2cc
+SRC_COLLECTION = "6c54cade-bde5-45c1-bdea-f4bd71dba2cc"
+SRC_PATH = "/share/godata/file1.txt"
+
+# Globus Tutorial Collection 2
+# https://app.globus.org/file-manager/collections/31ce9ba0-176d-45a5-add3-f37d233ba47d
+DST_COLLECTION = "31ce9ba0-176d-45a5-add3-f37d233ba47d"
+DST_PATH = "/~/example-transfer-script-destination.txt"
+
+
+def main():
+    transfer_client = globus_sdk.TransferClient(app=USER_APP)
+
+    # Comment out each of these lines if the referenced collection is either
+    #   (1) A guest collection or (2) high assurance.
+    transfer_client.add_app_data_access_scope(SRC_COLLECTION)
+    transfer_client.add_app_data_access_scope(DST_COLLECTION)
+
+    transfer_request = globus_sdk.TransferData(
+        source_endpoint=SRC_COLLECTION,
+        destination_endpoint=DST_COLLECTION,
+    )
+    transfer_request.add_item(SRC_PATH, DST_PATH)
+
+    task = transfer_client.submit_transfer(transfer_request)
+    print(f"Submitted transfer. Task ID: {task['task_id']}.")
+
+
+if __name__ == "__main__":
+    main()

docs/experimental/examples/transferring_data/submit_transfer/submit_transfer_reactive_consent_required.py

@@ -0,0 +1,42 @@
+import globus_sdk
+from globus_sdk.experimental.globus_app import UserApp
+
+# Tutorial Client ID - <replace this with your own client>
+NATIVE_CLIENT_ID = "61338d24-54d5-408f-a10d-66c06b59f6d2"
+USER_APP = UserApp("my-simple-transfer", client_id=NATIVE_CLIENT_ID)
+
+# Globus Tutorial Collection 1
+# https://app.globus.org/file-manager/collections/6c54cade-bde5-45c1-bdea-f4bd71dba2cc
+SRC_COLLECTION = "6c54cade-bde5-45c1-bdea-f4bd71dba2cc"
+SRC_PATH = "/share/godata/file1.txt"
+
+# Globus Tutorial Collection 2
+# https://app.globus.org/file-manager/collections/31ce9ba0-176d-45a5-add3-f37d233ba47d
+DST_COLLECTION = "31ce9ba0-176d-45a5-add3-f37d233ba47d"
+DST_PATH = "/~/example-transfer-script-destination.txt"
+
+
+def main():
+    transfer_client = globus_sdk.TransferClient(app=USER_APP)
+
+    transfer_request = globus_sdk.TransferData(
+        source_endpoint=SRC_COLLECTION,
+        destination_endpoint=DST_COLLECTION,
+    )
+    transfer_request.add_item(SRC_PATH, DST_PATH)
+
+    try:
+        task = transfer_client.submit_transfer(transfer_request)
+    except globus_sdk.TransferAPIError as err:
+        if not err.info.consent_required:
+            raise
+
+        print("Additional consent required.")
+        transfer_client.add_app_scope(err.info.consent_required.required_scopes)
+
+        task = transfer_client.submit_transfer(transfer_request)
+    print(f"Submitted transfer. Task ID: {task['task_id']}.")
+
+
+if __name__ == "__main__":
+    main()

docs/experimental/examples/transferring_data/task_deadlines.rst

@@ -0,0 +1,5 @@
+
+Setting Task Deadlines
+======================
+
+TODO

docs/index.rst

@@ -45,6 +45,8 @@ Table of Contents
 
     testing/index
     experimental/index
+    experimental/examples/index
+
 
 .. toctree::
     :caption: Additional Info