Fix documentation examples (#676)

## Changes Split examples in workspace and account examples to avoid workspace examples showing in account services which share a name. ## Tests - [X] Generated documentation - [X] `make test` run locally - [X] `make fmt` applied - [ ] relevant integration tests applied
databricks · Jun 17, 2024 · 9eaaf1e · 9eaaf1e
1 parent f50af60
commit 9eaaf1e
Show file tree

Hide file tree

Showing 315 changed files with 331 additions and 674 deletions.
diff --git a/.codegen.json b/.codegen.json
@@ -12,7 +12,7 @@
     ".codegen/error_overrides.py.tmpl": "databricks/sdk/errors/overrides.py"
   },
   "samples": {
-    ".codegen/example.py.tmpl": "examples/{{.Service.SnakeName}}/{{.Method.SnakeName}}_{{.SnakeName}}.py"
+    ".codegen/example.py.tmpl": "examples/{{if .IsAccount}}account{{else}}workspace{{end}}/{{.Service.SnakeName}}/{{.Method.SnakeName}}_{{.SnakeName}}.py"
   },
   "version": {
     "databricks/sdk/version.py": "__version__ = '$VERSION'"

diff --git a/.gitattributes b/.gitattributes
diff --git a/docs/account/catalog/metastores.rst b/docs/account/catalog/metastores.rst
@@ -9,25 +9,6 @@
 
     .. py:method:: create( [, metastore_info: Optional[CreateMetastore]]) -> AccountsMetastoreInfo
 
-
-        Usage:
-
-        .. code-block::
-
-            import os
-            import time
-            
-            from databricks.sdk import WorkspaceClient
-            
-            w = WorkspaceClient()
-            
-            created = w.metastores.create(name=f'sdk-{time.time_ns()}',
-                                          storage_root="s3://%s/%s" %
-                                          (os.environ["TEST_BUCKET"], f'sdk-{time.time_ns()}'))
-            
-            # cleanup
-            w.metastores.delete(id=created.metastore_id, force=True)
-
         Create metastore.
 
         Creates a Unity Catalog metastore.
@@ -53,27 +34,6 @@
 
     .. py:method:: get(metastore_id: str) -> AccountsMetastoreInfo
 
-
-        Usage:
-
-        .. code-block::
-
-            import os
-            import time
-            
-            from databricks.sdk import WorkspaceClient
-            
-            w = WorkspaceClient()
-            
-            created = w.metastores.create(name=f'sdk-{time.time_ns()}',
-                                          storage_root="s3://%s/%s" %
-                                          (os.environ["TEST_BUCKET"], f'sdk-{time.time_ns()}'))
-            
-            _ = w.metastores.get(id=created.metastore_id)
-            
-            # cleanup
-            w.metastores.delete(id=created.metastore_id, force=True)
-
         Get a metastore.
 
         Gets a Unity Catalog metastore from an account, both specified by ID.
@@ -86,17 +46,6 @@
 
     .. py:method:: list() -> Iterator[MetastoreInfo]
 
-
-        Usage:
-
-        .. code-block::
-
-            from databricks.sdk import WorkspaceClient
-            
-            w = WorkspaceClient()
-            
-            all = w.metastores.list()
-
         Get all metastores associated with an account.
 
         Gets all Unity Catalog metastores associated with an account specified by ID.
@@ -106,27 +55,6 @@
 
     .. py:method:: update(metastore_id: str [, metastore_info: Optional[UpdateMetastore]]) -> AccountsMetastoreInfo
 
-
-        Usage:
-
-        .. code-block::
-
-            import os
-            import time
-            
-            from databricks.sdk import WorkspaceClient
-            
-            w = WorkspaceClient()
-            
-            created = w.metastores.create(name=f'sdk-{time.time_ns()}',
-                                          storage_root="s3://%s/%s" %
-                                          (os.environ["TEST_BUCKET"], f'sdk-{time.time_ns()}'))
-            
-            _ = w.metastores.update(id=created.metastore_id, new_name=f'sdk-{time.time_ns()}')
-            
-            # cleanup
-            w.metastores.delete(id=created.metastore_id, force=True)
-
         Update a metastore.
 
         Updates an existing Unity Catalog metastore.

diff --git a/docs/account/catalog/storage_credentials.rst b/docs/account/catalog/storage_credentials.rst
@@ -8,26 +8,6 @@
 
     .. py:method:: create(metastore_id: str [, credential_info: Optional[CreateStorageCredential]]) -> AccountsStorageCredentialInfo
 
-
-        Usage:
-
-        .. code-block::
-
-            import os
-            import time
-            
-            from databricks.sdk import WorkspaceClient
-            from databricks.sdk.service import catalog
-            
-            w = WorkspaceClient()
-            
-            created = w.storage_credentials.create(
-                name=f'sdk-{time.time_ns()}',
-                aws_iam_role=catalog.AwsIamRole(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"]))
-            
-            # cleanup
-            w.storage_credentials.delete(delete=created.name)
-
         Create a storage credential.
 
         Creates a new storage credential. The request object is specific to the cloud:
@@ -64,28 +44,6 @@
 
     .. py:method:: get(metastore_id: str, storage_credential_name: str) -> AccountsStorageCredentialInfo
 
-
-        Usage:
-
-        .. code-block::
-
-            import os
-            import time
-            
-            from databricks.sdk import WorkspaceClient
-            from databricks.sdk.service import catalog
-            
-            w = WorkspaceClient()
-            
-            created = w.storage_credentials.create(
-                name=f'sdk-{time.time_ns()}',
-                aws_iam_role=catalog.AwsIamRoleRequest(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"]))
-            
-            by_name = w.storage_credentials.get(name=created.name)
-            
-            # cleanup
-            w.storage_credentials.delete(name=created.name)
-
         Gets the named storage credential.
 
         Gets a storage credential from the metastore. The caller must be a metastore admin, the owner of the
@@ -101,17 +59,6 @@
 
     .. py:method:: list(metastore_id: str) -> Iterator[StorageCredentialInfo]
 
-
-        Usage:
-
-        .. code-block::
-
-            from databricks.sdk import WorkspaceClient
-            
-            w = WorkspaceClient()
-            
-            all = w.storage_credentials.list()
-
         Get all storage credentials assigned to a metastore.
 
         Gets a list of all storage credentials that have been assigned to given metastore.
@@ -124,31 +71,6 @@
 
     .. py:method:: update(metastore_id: str, storage_credential_name: str [, credential_info: Optional[UpdateStorageCredential]]) -> AccountsStorageCredentialInfo
 
-
-        Usage:
-
-        .. code-block::
-
-            import os
-            import time
-            
-            from databricks.sdk import WorkspaceClient
-            from databricks.sdk.service import catalog
-            
-            w = WorkspaceClient()
-            
-            created = w.storage_credentials.create(
-                name=f'sdk-{time.time_ns()}',
-                aws_iam_role=catalog.AwsIamRole(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"]))
-            
-            _ = w.storage_credentials.update(
-                name=created.name,
-                comment=f'sdk-{time.time_ns()}',
-                aws_iam_role=catalog.AwsIamRole(role_arn=os.environ["TEST_METASTORE_DATA_ACCESS_ARN"]))
-            
-            # cleanup
-            w.storage_credentials.delete(delete=created.name)
-
         Updates a storage credential.
 
         Updates a storage credential on the metastore. The caller must be the owner of the storage credential.

diff --git a/docs/account/iam/groups.rst b/docs/account/iam/groups.rst
@@ -13,22 +13,6 @@
 
     .. py:method:: create( [, display_name: Optional[str], entitlements: Optional[List[ComplexValue]], external_id: Optional[str], groups: Optional[List[ComplexValue]], id: Optional[str], members: Optional[List[ComplexValue]], meta: Optional[ResourceMeta], roles: Optional[List[ComplexValue]], schemas: Optional[List[GroupSchema]]]) -> Group
 
-
-        Usage:
-
-        .. code-block::
-
-            import time
-            
-            from databricks.sdk import WorkspaceClient
-            
-            w = WorkspaceClient()
-            
-            group = w.groups.create(display_name=f'sdk-{time.time_ns()}')
-            
-            # cleanup
-            w.groups.delete(id=group.id)
-
         Create a new group.
 
         Creates a group in the Databricks account with a unique name, using the supplied group details.
@@ -57,21 +41,6 @@
 
     .. py:method:: delete(id: str)
 
-
-        Usage:
-
-        .. code-block::
-
-            import time
-            
-            from databricks.sdk import WorkspaceClient
-            
-            w = WorkspaceClient()
-            
-            group = w.groups.create(display_name=f'sdk-{time.time_ns()}')
-            
-            w.groups.delete(id=group.id)
-
         Delete a group.
 
         Deletes a group from the Databricks account.
@@ -84,24 +53,6 @@
 
     .. py:method:: get(id: str) -> Group
 
-
-        Usage:
-
-        .. code-block::
-
-            import time
-            
-            from databricks.sdk import WorkspaceClient
-            
-            w = WorkspaceClient()
-            
-            group = w.groups.create(display_name=f'sdk-{time.time_ns()}')
-            
-            fetch = w.groups.get(id=group.id)
-            
-            # cleanup
-            w.groups.delete(id=group.id)
-
         Get group details.
 
         Gets the information for a specific group in the Databricks account.
@@ -143,36 +94,6 @@
 
     .. py:method:: patch(id: str [, operations: Optional[List[Patch]], schemas: Optional[List[PatchSchema]]])
 
-
-        Usage:
-
-        .. code-block::
-
-            import time
-            from databricks.sdk import WorkspaceClient
-            from databricks.sdk.service import iam
-            
-            w = WorkspaceClient()
-            
-            group = w.groups.create(display_name=f'sdk-{time.time_ns()}-group')
-            user = w.users.create(
-                display_name=f'sdk-{time.time_ns()}-user', user_name=f'sdk-{time.time_ns()}@example.com')
-            
-            w.groups.patch(
-                id=group.id,
-                operations=[iam.Patch(
-                    op=iam.PatchOp.ADD,
-                    value={"members": [{
-                        "value": user.id,
-                    }]},
-                )],
-                schemas=[iam.PatchSchema.URN_IETF_PARAMS_SCIM_API_MESSAGES_2_0_PATCH_OP],
-            )
-            
-            # cleanup
-            w.users.delete(id=user.id)
-            w.groups.delete(id=group.id)
-
         Update group details.
 
         Partially updates the details of a group.

diff --git a/docs/account/iam/service_principals.rst b/docs/account/iam/service_principals.rst
@@ -19,18 +19,14 @@
 
             import time
             
-            from databricks.sdk import WorkspaceClient
-            from databricks.sdk.service import iam
-            
-            w = WorkspaceClient()
+            from databricks.sdk import AccountClient
             
-            groups = w.groups.group_display_name_to_id_map(iam.ListGroupsRequest())
+            a = AccountClient()
             
-            spn = w.service_principals.create(display_name=f'sdk-{time.time_ns()}',
-                                              groups=[iam.ComplexValue(value=groups["admins"])])
+            sp_create = a.service_principals.create(active=True, display_name=f'sdk-{time.time_ns()}')
             
             # cleanup
-            w.service_principals.delete(id=spn.id)
+            a.service_principals.delete(id=sp_create.id)
 
         Create a service principal.
 
@@ -80,16 +76,16 @@
 
             import time
             
-            from databricks.sdk import WorkspaceClient
+            from databricks.sdk import AccountClient
             
-            w = WorkspaceClient()
+            a = AccountClient()
             
-            created = w.service_principals.create(display_name=f'sdk-{time.time_ns()}')
+            sp_create = a.service_principals.create(active=True, display_name=f'sdk-{time.time_ns()}')
             
-            by_id = w.service_principals.get(id=created.id)
+            sp = a.service_principals.get(id=sp_create.id)
             
             # cleanup
-            w.service_principals.delete(id=created.id)
+            a.service_principals.delete(id=sp_create.id)
 
         Get service principal details.
 
@@ -197,19 +193,18 @@
 
             import time
             
-            from databricks.sdk import WorkspaceClient
-            from databricks.sdk.service import iam
+            from databricks.sdk import AccountClient
             
-            w = WorkspaceClient()
+            a = AccountClient()
             
-            created = w.service_principals.create(display_name=f'sdk-{time.time_ns()}')
+            sp_create = a.service_principals.create(active=True, display_name=f'sdk-{time.time_ns()}')
+            
+            sp = a.service_principals.get(id=sp_create.id)
             
-            w.service_principals.update(id=created.id,
-                                        display_name=f'sdk-{time.time_ns()}',
-                                        roles=[iam.ComplexValue(value="xyz")])
+            a.service_principals.update(active=True, display_name=sp.display_name, id=sp.id)
             
             # cleanup
-            w.service_principals.delete(id=created.id)
+            a.service_principals.delete(id=sp_create.id)
 
         Replace service principal.