From 4199b9ae3518429380bc60aab5d3f328a60ad2c8 Mon Sep 17 00:00:00 2001 From: Serge Smertin Date: Thu, 12 Sep 2024 11:05:10 +0200 Subject: [PATCH] Added documentation for `make_secret_scope` and `make_secret_scope_acl` --- README.md | 127 ++++++++---------- scripts/gen-readme.py | 2 +- .../labs/pytester/fixtures/secrets.py | 87 +++++------- src/databricks/labs/pytester/py.typed | 1 + tests/integration/fixtures/test_secrets.py | 24 ++++ tests/integration/test_fixtures.py | 11 -- 6 files changed, 114 insertions(+), 138 deletions(-) create mode 100644 src/databricks/labs/pytester/py.typed create mode 100644 tests/integration/fixtures/test_secrets.py diff --git a/README.md b/README.md index 17586e0..7430665 100644 --- a/README.md +++ b/README.md @@ -85,7 +85,7 @@ This will load the `ws` environment from the `~/.databricks/debug-env.json` file If any of the environment variables are not found, [`env_or_skip` fixture](#env_or_skip-fixture) will gracefully skip the execution of tests. -See also [`debug_env` fixture](#debug_env-fixture). +See also [`debug_env`](#debug_env-fixture). [[back to top](#python-testing-for-databricks)] @@ -95,7 +95,7 @@ Loads environment variables specified in [`debug_env_name` fixture](#debug_env_n for local debugging in IDEs, otherwise allowing the tests to run with the default environment variables specified in the CI/CD pipeline. -See also [`env_or_skip` fixture](#env_or_skip-fixture), [`ws` fixture](#ws-fixture), [`debug_env_name` fixture](#debug_env_name-fixture). +See also [`env_or_skip`](#env_or_skip-fixture), [`ws`](#ws-fixture), [`debug_env_name`](#debug_env_name-fixture). [[back to top](#python-testing-for-databricks)] @@ -114,7 +114,7 @@ def test_something(env_or_skip): assert token is not None ``` -See also [`make_udf` fixture](#make_udf-fixture), [`sql_backend` fixture](#sql_backend-fixture), [`debug_env` fixture](#debug_env-fixture). +See also [`make_udf`](#make_udf-fixture), [`sql_backend`](#sql_backend-fixture), [`debug_env`](#debug_env-fixture). [[back to top](#python-testing-for-databricks)] @@ -137,7 +137,7 @@ def test_workspace_operations(ws): assert len(clusters) >= 0 ``` -See also [`make_catalog` fixture](#make_catalog-fixture), [`make_cluster` fixture](#make_cluster-fixture), [`make_cluster_policy` fixture](#make_cluster_policy-fixture), [`make_directory` fixture](#make_directory-fixture), [`make_group` fixture](#make_group-fixture), [`make_instance_pool` fixture](#make_instance_pool-fixture), [`make_job` fixture](#make_job-fixture), [`make_notebook` fixture](#make_notebook-fixture), [`make_repo` fixture](#make_repo-fixture), [`make_schema` fixture](#make_schema-fixture), [`make_secret_scope` fixture](#make_secret_scope-fixture), [`make_secret_scope_acl` fixture](#make_secret_scope_acl-fixture), [`make_table` fixture](#make_table-fixture), [`make_udf` fixture](#make_udf-fixture), [`make_user` fixture](#make_user-fixture), [`sql_backend` fixture](#sql_backend-fixture), [`workspace_library` fixture](#workspace_library-fixture), [`debug_env` fixture](#debug_env-fixture), [`product_info` fixture](#product_info-fixture). +See also [`make_catalog`](#make_catalog-fixture), [`make_cluster`](#make_cluster-fixture), [`make_cluster_policy`](#make_cluster_policy-fixture), [`make_directory`](#make_directory-fixture), [`make_group`](#make_group-fixture), [`make_instance_pool`](#make_instance_pool-fixture), [`make_job`](#make_job-fixture), [`make_notebook`](#make_notebook-fixture), [`make_repo`](#make_repo-fixture), [`make_schema`](#make_schema-fixture), [`make_secret_scope`](#make_secret_scope-fixture), [`make_secret_scope_acl`](#make_secret_scope_acl-fixture), [`make_table`](#make_table-fixture), [`make_udf`](#make_udf-fixture), [`make_user`](#make_user-fixture), [`sql_backend`](#sql_backend-fixture), [`workspace_library`](#workspace_library-fixture), [`debug_env`](#debug_env-fixture), [`product_info`](#product_info-fixture). [[back to top](#python-testing-for-databricks)] @@ -163,7 +163,7 @@ random_string = make_random(k=8) assert len(random_string) == 8 ``` -See also [`make_catalog` fixture](#make_catalog-fixture), [`make_cluster` fixture](#make_cluster-fixture), [`make_cluster_policy` fixture](#make_cluster_policy-fixture), [`make_directory` fixture](#make_directory-fixture), [`make_group` fixture](#make_group-fixture), [`make_instance_pool` fixture](#make_instance_pool-fixture), [`make_job` fixture](#make_job-fixture), [`make_notebook` fixture](#make_notebook-fixture), [`make_repo` fixture](#make_repo-fixture), [`make_schema` fixture](#make_schema-fixture), [`make_secret_scope` fixture](#make_secret_scope-fixture), [`make_table` fixture](#make_table-fixture), [`make_udf` fixture](#make_udf-fixture), [`make_user` fixture](#make_user-fixture), [`workspace_library` fixture](#workspace_library-fixture). +See also [`make_catalog`](#make_catalog-fixture), [`make_cluster`](#make_cluster-fixture), [`make_cluster_policy`](#make_cluster_policy-fixture), [`make_directory`](#make_directory-fixture), [`make_group`](#make_group-fixture), [`make_instance_pool`](#make_instance_pool-fixture), [`make_job`](#make_job-fixture), [`make_notebook`](#make_notebook-fixture), [`make_repo`](#make_repo-fixture), [`make_schema`](#make_schema-fixture), [`make_secret_scope`](#make_secret_scope-fixture), [`make_table`](#make_table-fixture), [`make_udf`](#make_udf-fixture), [`make_user`](#make_user-fixture), [`workspace_library`](#workspace_library-fixture). [[back to top](#python-testing-for-databricks)] @@ -196,7 +196,7 @@ To manage Databricks instance pools using the make_instance_pool fixture: instance_pool_info = make_instance_pool(instance_pool_name="my-pool") assert instance_pool_info is not None -See also [`ws` fixture](#ws-fixture), [`make_random` fixture](#make_random-fixture). +See also [`ws`](#ws-fixture), [`make_random`](#make_random-fixture). [[back to top](#python-testing-for-databricks)] @@ -231,7 +231,7 @@ To manage Databricks jobs using the make_job fixture: job_info = make_job(name="my-job") assert job_info is not None -See also [`ws` fixture](#ws-fixture), [`make_random` fixture](#make_random-fixture), [`make_notebook` fixture](#make_notebook-fixture). +See also [`ws`](#ws-fixture), [`make_random`](#make_random-fixture), [`make_notebook`](#make_notebook-fixture). [[back to top](#python-testing-for-databricks)] @@ -264,7 +264,7 @@ To manage Databricks clusters using the make_cluster fixture: cluster_info = make_cluster(cluster_name="my-cluster", single_node=True) assert cluster_info is not None -See also [`ws` fixture](#ws-fixture), [`make_random` fixture](#make_random-fixture). +See also [`ws`](#ws-fixture), [`make_random`](#make_random-fixture). [[back to top](#python-testing-for-databricks)] @@ -297,7 +297,7 @@ To manage Databricks cluster policies using the make_cluster_policy fixture: policy_info = make_cluster_policy(name="my-policy") assert policy_info is not None -See also [`ws` fixture](#ws-fixture), [`make_random` fixture](#make_random-fixture). +See also [`ws`](#ws-fixture), [`make_random`](#make_random-fixture). [[back to top](#python-testing-for-databricks)] @@ -330,7 +330,7 @@ To manage Databricks workspace groups using the make_group fixture: group_info = make_group(members=["user@example.com"], roles=["viewer"]) assert group_info is not None -See also [`ws` fixture](#ws-fixture), [`make_random` fixture](#make_random-fixture). +See also [`ws`](#ws-fixture), [`make_random`](#make_random-fixture). [[back to top](#python-testing-for-databricks)] @@ -363,7 +363,7 @@ To manage Databricks workspace users using the make_user fixture: user_info = make_user() assert user_info is not None -See also [`ws` fixture](#ws-fixture), [`make_random` fixture](#make_random-fixture). +See also [`ws`](#ws-fixture), [`make_random`](#make_random-fixture). [[back to top](#python-testing-for-databricks)] @@ -396,7 +396,7 @@ To manage Databricks notebooks using the make_notebook fixture: notebook_path = make_notebook() assert notebook_path.startswith("/Users/") and notebook_path.endswith(".py") -See also [`make_job` fixture](#make_job-fixture), [`ws` fixture](#ws-fixture), [`make_random` fixture](#make_random-fixture). +See also [`make_job`](#make_job-fixture), [`ws`](#ws-fixture), [`make_random`](#make_random-fixture). [[back to top](#python-testing-for-databricks)] @@ -429,7 +429,7 @@ To manage Databricks directories using the make_directory fixture: directory_path = make_directory() assert directory_path.startswith("/Users/") and not directory_path.endswith(".py") -See also [`ws` fixture](#ws-fixture), [`make_random` fixture](#make_random-fixture). +See also [`ws`](#ws-fixture), [`make_random`](#make_random-fixture). [[back to top](#python-testing-for-databricks)] @@ -462,77 +462,58 @@ To manage Databricks repos using the make_repo fixture: repo_info = make_repo() assert repo_info is not None -See also [`ws` fixture](#ws-fixture), [`make_random` fixture](#make_random-fixture). +See also [`ws`](#ws-fixture), [`make_random`](#make_random-fixture). [[back to top](#python-testing-for-databricks)] ### `make_secret_scope` fixture -Fixture to create secret scopes. +This fixture provides a function to create secret scopes. The created secret scope will be +deleted after the test is complete. Returns the name of the secret scope. -This fixture provides a function to create secret scopes using the provided workspace (ws) -and the make_random function for generating unique names. The created secret scope will be -deleted after the test is complete. - -Parameters: ------------ -ws : WorkspaceClient - A Databricks WorkspaceClient instance. -make_random : function - The make_random fixture to generate unique names. - -Returns: --------- -function: - A function to create secret scopes. - -Usage Example: --------------- To create a secret scope and use it within a test function: -.. code-block:: python - - def test_secret_scope_creation(make_secret_scope): - secret_scope_name = make_secret_scope() - assert secret_scope_name.startswith("sdk-") +```python +def test_secret_scope_creation(make_secret_scope): + secret_scope_name = make_secret_scope() + assert secret_scope_name.startswith("dummy-") +``` -See also [`ws` fixture](#ws-fixture), [`make_random` fixture](#make_random-fixture). +See also [`ws`](#ws-fixture), [`make_random`](#make_random-fixture). [[back to top](#python-testing-for-databricks)] ### `make_secret_scope_acl` fixture -Fixture to manage secret scope access control lists (ACLs). - -This fixture provides a function to manage access control lists (ACLs) for secret scopes -using the provided workspace (ws). ACLs define permissions for principals (users or groups) -on specific secret scopes. +This fixture provides a function to manage access control lists (ACLs) for secret scopes. +ACLs define permissions for principals (users or groups) on specific secret scopes. -Parameters: ------------ -ws : WorkspaceClient - A Databricks WorkspaceClient instance. +Arguments: +- `scope`: The name of the secret scope. +- `principal`: The name of the principal (user or group). +- `permission`: The permission level for the principal on the secret scope. -Returns: --------- -function: - A function to manage secret scope ACLs. +Returns a tuple containing the secret scope name and the principal name. -Usage Example: --------------- To manage secret scope ACLs using the make_secret_scope_acl fixture: -.. code-block:: python - - def test_secret_scope_acl_management(make_secret_scope_acl): - scope_name = "my_secret_scope" - principal_name = "user@example.com" - permission = workspace.AclPermission.READ - - acl_info = make_secret_scope_acl(scope=scope_name, principal=principal_name, permission=permission) - assert acl_info == (scope_name, principal_name) +```python +from databricks.sdk.service.workspace import AclPermission + +def test_secret_scope_acl_management(make_user, make_secret_scope, make_secret_scope_acl): + scope_name = make_secret_scope() + principal_name = make_user().display_name + permission = AclPermission.READ + + acl_info = make_secret_scope_acl( + scope=scope_name, + principal=principal_name, + permission=permission, + ) + assert acl_info == (scope_name, principal_name) +``` -See also [`ws` fixture](#ws-fixture). +See also [`ws`](#ws-fixture). [[back to top](#python-testing-for-databricks)] @@ -540,7 +521,7 @@ See also [`ws` fixture](#ws-fixture). ### `make_udf` fixture _No description yet._ -See also [`ws` fixture](#ws-fixture), [`env_or_skip` fixture](#env_or_skip-fixture), [`sql_backend` fixture](#sql_backend-fixture), [`make_schema` fixture](#make_schema-fixture), [`make_random` fixture](#make_random-fixture). +See also [`ws`](#ws-fixture), [`env_or_skip`](#env_or_skip-fixture), [`sql_backend`](#sql_backend-fixture), [`make_schema`](#make_schema-fixture), [`make_random`](#make_random-fixture). [[back to top](#python-testing-for-databricks)] @@ -548,7 +529,7 @@ See also [`ws` fixture](#ws-fixture), [`env_or_skip` fixture](#env_or_skip-fixtu ### `make_catalog` fixture _No description yet._ -See also [`ws` fixture](#ws-fixture), [`sql_backend` fixture](#sql_backend-fixture), [`make_random` fixture](#make_random-fixture). +See also [`ws`](#ws-fixture), [`sql_backend`](#sql_backend-fixture), [`make_random`](#make_random-fixture). [[back to top](#python-testing-for-databricks)] @@ -556,7 +537,7 @@ See also [`ws` fixture](#ws-fixture), [`sql_backend` fixture](#sql_backend-fixtu ### `make_schema` fixture _No description yet._ -See also [`make_table` fixture](#make_table-fixture), [`make_udf` fixture](#make_udf-fixture), [`ws` fixture](#ws-fixture), [`sql_backend` fixture](#sql_backend-fixture), [`make_random` fixture](#make_random-fixture). +See also [`make_table`](#make_table-fixture), [`make_udf`](#make_udf-fixture), [`ws`](#ws-fixture), [`sql_backend`](#sql_backend-fixture), [`make_random`](#make_random-fixture). [[back to top](#python-testing-for-databricks)] @@ -564,7 +545,7 @@ See also [`make_table` fixture](#make_table-fixture), [`make_udf` fixture](#make ### `make_table` fixture _No description yet._ -See also [`ws` fixture](#ws-fixture), [`sql_backend` fixture](#sql_backend-fixture), [`make_schema` fixture](#make_schema-fixture), [`make_random` fixture](#make_random-fixture). +See also [`ws`](#ws-fixture), [`sql_backend`](#sql_backend-fixture), [`make_schema`](#make_schema-fixture), [`make_random`](#make_random-fixture). [[back to top](#python-testing-for-databricks)] @@ -572,7 +553,7 @@ See also [`ws` fixture](#ws-fixture), [`sql_backend` fixture](#sql_backend-fixtu ### `product_info` fixture _No description yet._ -See also [`ws` fixture](#ws-fixture). +See also [`ws`](#ws-fixture). [[back to top](#python-testing-for-databricks)] @@ -582,7 +563,7 @@ te and provide a SQL backend for executing statements. Requires the environment variable `DATABRICKS_WAREHOUSE_ID` to be set. -See also [`make_catalog` fixture](#make_catalog-fixture), [`make_schema` fixture](#make_schema-fixture), [`make_table` fixture](#make_table-fixture), [`make_udf` fixture](#make_udf-fixture), [`sql_exec` fixture](#sql_exec-fixture), [`sql_fetch_all` fixture](#sql_fetch_all-fixture), [`ws` fixture](#ws-fixture), [`env_or_skip` fixture](#env_or_skip-fixture). +See also [`make_catalog`](#make_catalog-fixture), [`make_schema`](#make_schema-fixture), [`make_table`](#make_table-fixture), [`make_udf`](#make_udf-fixture), [`sql_exec`](#sql_exec-fixture), [`sql_fetch_all`](#sql_fetch_all-fixture), [`ws`](#ws-fixture), [`env_or_skip`](#env_or_skip-fixture). [[back to top](#python-testing-for-databricks)] @@ -590,7 +571,7 @@ See also [`make_catalog` fixture](#make_catalog-fixture), [`make_schema` fixture ### `sql_exec` fixture ute SQL statement and don't return any results. -See also [`sql_backend` fixture](#sql_backend-fixture). +See also [`sql_backend`](#sql_backend-fixture). [[back to top](#python-testing-for-databricks)] @@ -598,7 +579,7 @@ See also [`sql_backend` fixture](#sql_backend-fixture). ### `sql_fetch_all` fixture h all rows from a SQL statement. -See also [`sql_backend` fixture](#sql_backend-fixture). +See also [`sql_backend`](#sql_backend-fixture). [[back to top](#python-testing-for-databricks)] @@ -606,7 +587,7 @@ See also [`sql_backend` fixture](#sql_backend-fixture). ### `workspace_library` fixture _No description yet._ -See also [`ws` fixture](#ws-fixture), [`make_random` fixture](#make_random-fixture). +See also [`ws`](#ws-fixture), [`make_random`](#make_random-fixture). [[back to top](#python-testing-for-databricks)] diff --git a/scripts/gen-readme.py b/scripts/gen-readme.py index 0e46459..31ff29b 100644 --- a/scripts/gen-readme.py +++ b/scripts/gen-readme.py @@ -24,7 +24,7 @@ class Fixture: @staticmethod def ref(name: str) -> str: - return f"[`{name}` fixture](#{name}-fixture)" + return f"[`{name}`](#{name}-fixture)" def usage(self) -> str: lines = "\n".join(_[4:] for _ in self.description.split("\n")) diff --git a/src/databricks/labs/pytester/fixtures/secrets.py b/src/databricks/labs/pytester/fixtures/secrets.py index b99dc17..9259d9c 100644 --- a/src/databricks/labs/pytester/fixtures/secrets.py +++ b/src/databricks/labs/pytester/fixtures/secrets.py @@ -1,82 +1,63 @@ -import pytest +from pytest import fixture from databricks.sdk import WorkspaceClient from databricks.sdk.service import workspace from databricks.labs.pytester.fixtures.baseline import factory -@pytest.fixture +@fixture def make_secret_scope(ws: WorkspaceClient, make_random): """ - Fixture to create secret scopes. - - This fixture provides a function to create secret scopes using the provided workspace (ws) - and the make_random function for generating unique names. The created secret scope will be - deleted after the test is complete. - - Parameters: - ----------- - ws : WorkspaceClient - A Databricks WorkspaceClient instance. - make_random : function - The make_random fixture to generate unique names. - - Returns: - -------- - function: - A function to create secret scopes. - - Usage Example: - -------------- - To create a secret scope and use it within a test function: + This fixture provides a function to create secret scopes. The created secret scope will be + deleted after the test is complete. Returns the name of the secret scope. - .. code-block:: python + To create a secret scope and use it within a test function: - def test_secret_scope_creation(make_secret_scope): - secret_scope_name = make_secret_scope() - assert secret_scope_name.startswith("sdk-") + ```python + def test_secret_scope_creation(make_secret_scope): + secret_scope_name = make_secret_scope() + assert secret_scope_name.startswith("dummy-") + ``` """ def create(**kwargs): - name = f"sdk-{make_random(4)}" + name = f"dummy-{make_random(4)}" ws.secrets.create_scope(name, **kwargs) return name yield from factory("secret scope", create, ws.secrets.delete_scope) -@pytest.fixture +@fixture def make_secret_scope_acl(ws: WorkspaceClient): """ - Fixture to manage secret scope access control lists (ACLs). - - This fixture provides a function to manage access control lists (ACLs) for secret scopes - using the provided workspace (ws). ACLs define permissions for principals (users or groups) - on specific secret scopes. + This fixture provides a function to manage access control lists (ACLs) for secret scopes. + ACLs define permissions for principals (users or groups) on specific secret scopes. - Parameters: - ----------- - ws : WorkspaceClient - A Databricks WorkspaceClient instance. + Arguments: + - `scope`: The name of the secret scope. + - `principal`: The name of the principal (user or group). + - `permission`: The permission level for the principal on the secret scope. - Returns: - -------- - function: - A function to manage secret scope ACLs. + Returns a tuple containing the secret scope name and the principal name. - Usage Example: - -------------- To manage secret scope ACLs using the make_secret_scope_acl fixture: - .. code-block:: python - - def test_secret_scope_acl_management(make_secret_scope_acl): - scope_name = "my_secret_scope" - principal_name = "user@example.com" - permission = workspace.AclPermission.READ - - acl_info = make_secret_scope_acl(scope=scope_name, principal=principal_name, permission=permission) - assert acl_info == (scope_name, principal_name) + ```python + from databricks.sdk.service.workspace import AclPermission + + def test_secret_scope_acl_management(make_user, make_secret_scope, make_secret_scope_acl): + scope_name = make_secret_scope() + principal_name = make_user().display_name + permission = AclPermission.READ + + acl_info = make_secret_scope_acl( + scope=scope_name, + principal=principal_name, + permission=permission, + ) + assert acl_info == (scope_name, principal_name) + ``` """ def create(*, scope: str, principal: str, permission: workspace.AclPermission): diff --git a/src/databricks/labs/pytester/py.typed b/src/databricks/labs/pytester/py.typed new file mode 100644 index 0000000..a643ecd --- /dev/null +++ b/src/databricks/labs/pytester/py.typed @@ -0,0 +1 @@ +# Marker file for PEP 561. The databricks-labs-blueprint package uses inline types. diff --git a/tests/integration/fixtures/test_secrets.py b/tests/integration/fixtures/test_secrets.py new file mode 100644 index 0000000..c3d927b --- /dev/null +++ b/tests/integration/fixtures/test_secrets.py @@ -0,0 +1,24 @@ +from databricks.sdk.service.workspace import AclPermission + + +def test_secret_scope_creation(make_secret_scope): + secret_scope_name = make_secret_scope() + assert secret_scope_name.startswith("dummy-") + + +def test_secret_scope_acl_management(make_user, make_secret_scope, make_secret_scope_acl): + scope_name = make_secret_scope() + principal_name = make_user().display_name + permission = AclPermission.READ + + acl_info = make_secret_scope_acl( + scope=scope_name, + principal=principal_name, + permission=permission, + ) + assert acl_info == (scope_name, principal_name) + + +def test_secret_scope_acl(make_secret_scope, make_secret_scope_acl, make_group): + scope_name = make_secret_scope() + make_secret_scope_acl(scope=scope_name, principal=make_group().display_name, permission=AclPermission.WRITE) diff --git a/tests/integration/test_fixtures.py b/tests/integration/test_fixtures.py index eaeb34a..231f4b3 100644 --- a/tests/integration/test_fixtures.py +++ b/tests/integration/test_fixtures.py @@ -1,8 +1,6 @@ import logging import os -from databricks.sdk.service.workspace import AclPermission - logger = logging.getLogger(__name__) @@ -15,15 +13,6 @@ def test_group(make_group, make_user): logger.info(f'created {make_group(display_name="abc", members=[make_user().id])}') -def test_secret_scope(make_secret_scope): - logger.info(f"created {make_secret_scope()}") - - -def test_secret_scope_acl(make_secret_scope, make_secret_scope_acl, make_group): - scope_name = make_secret_scope() - make_secret_scope_acl(scope=scope_name, principal=make_group().display_name, permission=AclPermission.WRITE) - - def test_notebook(make_notebook): logger.info(f"created {make_notebook()}")