From 29746e1984fc3942d830f54a9e921151d4d720c1 Mon Sep 17 00:00:00 2001 From: Yoshi Automation Bot Date: Wed, 6 Jan 2021 08:53:59 -0800 Subject: [PATCH] feat: add from_service_account_info factory and fix sphinx identifiers (#48) feat: add 'from_service_account_info' factory to clients fix: fix sphinx identifiers PiperOrigin-RevId: 350246057 Source-Author: Google APIs Source-Date: Tue Jan 5 16:44:11 2021 -0800 Source-Repo: googleapis/googleapis Source-Sha: 520682435235d9c503983a360a2090025aa47cd1 Source-Link: https://github.com/googleapis/googleapis/commit/520682435235d9c503983a360a2090025aa47cd1 --- docs/credentials_v1/iam_credentials.rst | 6 ++ docs/credentials_v1/services.rst | 6 +- docs/credentials_v1/types.rst | 1 + .../services/iam_credentials/async_client.py | 32 +++++--- .../services/iam_credentials/client.py | 79 +++++++++++++------ .../cloud/iam_credentials_v1/types/common.py | 4 +- synth.metadata | 7 +- .../credentials_v1/test_iam_credentials.py | 28 +++++-- 8 files changed, 115 insertions(+), 48 deletions(-) create mode 100644 docs/credentials_v1/iam_credentials.rst diff --git a/docs/credentials_v1/iam_credentials.rst b/docs/credentials_v1/iam_credentials.rst new file mode 100644 index 0000000..18a7000 --- /dev/null +++ b/docs/credentials_v1/iam_credentials.rst @@ -0,0 +1,6 @@ +IAMCredentials +-------------------------------- + +.. automodule:: google.cloud.iam_credentials_v1.services.iam_credentials + :members: + :inherited-members: diff --git a/docs/credentials_v1/services.rst b/docs/credentials_v1/services.rst index 13d1202..c47ca81 100644 --- a/docs/credentials_v1/services.rst +++ b/docs/credentials_v1/services.rst @@ -1,6 +1,6 @@ Services for Google Iam Credentials v1 API ========================================== +.. toctree:: + :maxdepth: 2 -.. automodule:: google.cloud.iam_credentials_v1.services.iam_credentials - :members: - :inherited-members: + iam_credentials diff --git a/docs/credentials_v1/types.rst b/docs/credentials_v1/types.rst index 8df2cf1..46e5276 100644 --- a/docs/credentials_v1/types.rst +++ b/docs/credentials_v1/types.rst @@ -3,4 +3,5 @@ Types for Google Iam Credentials v1 API .. automodule:: google.cloud.iam_credentials_v1.types :members: + :undoc-members: :show-inheritance: diff --git a/google/cloud/iam_credentials_v1/services/iam_credentials/async_client.py b/google/cloud/iam_credentials_v1/services/iam_credentials/async_client.py index 6c6dd71..557b525 100644 --- a/google/cloud/iam_credentials_v1/services/iam_credentials/async_client.py +++ b/google/cloud/iam_credentials_v1/services/iam_credentials/async_client.py @@ -89,6 +89,7 @@ class IAMCredentialsAsyncClient: IAMCredentialsClient.parse_common_location_path ) + from_service_account_info = IAMCredentialsClient.from_service_account_info from_service_account_file = IAMCredentialsClient.from_service_account_file from_service_account_json = from_service_account_file @@ -169,7 +170,7 @@ async def generate_access_token( account. Args: - request (:class:`~.common.GenerateAccessTokenRequest`): + request (:class:`google.cloud.iam_credentials_v1.types.GenerateAccessTokenRequest`): The request object. name (:class:`str`): Required. The resource name of the service account for @@ -178,6 +179,7 @@ async def generate_access_token( ``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-`` wildcard character is required; replacing it with a project ID is invalid. + This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -195,6 +197,7 @@ async def generate_access_token( ``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-`` wildcard character is required; replacing it with a project ID is invalid. + This corresponds to the ``delegates`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -205,16 +208,18 @@ async def generate_access_token( https://developers.google.com/identity/protocols/googlescopes for more information. At least one value required. + This corresponds to the ``scope`` field on the ``request`` instance; if ``request`` is provided, this should not be set. - lifetime (:class:`~.duration.Duration`): + lifetime (:class:`google.protobuf.duration_pb2.Duration`): The desired lifetime duration of the access token in seconds. Must be set to a value less than or equal to 3600 (1 hour). If a value is not specified, the token's lifetime will be set to a default value of one hour. + This corresponds to the ``lifetime`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -226,7 +231,7 @@ async def generate_access_token( sent along with the request as metadata. Returns: - ~.common.GenerateAccessTokenResponse: + google.cloud.iam_credentials_v1.types.GenerateAccessTokenResponse: """ # Create or coerce a protobuf request object. @@ -298,7 +303,7 @@ async def generate_id_token( account. Args: - request (:class:`~.common.GenerateIdTokenRequest`): + request (:class:`google.cloud.iam_credentials_v1.types.GenerateIdTokenRequest`): The request object. name (:class:`str`): Required. The resource name of the service account for @@ -307,6 +312,7 @@ async def generate_id_token( ``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-`` wildcard character is required; replacing it with a project ID is invalid. + This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -324,6 +330,7 @@ async def generate_id_token( ``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-`` wildcard character is required; replacing it with a project ID is invalid. + This corresponds to the ``delegates`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -331,6 +338,7 @@ async def generate_id_token( Required. The audience for the token, such as the API or account that this token grants access to. + This corresponds to the ``audience`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -338,6 +346,7 @@ async def generate_id_token( Include the service account email in the token. If set to ``true``, the token will contain ``email`` and ``email_verified`` claims. + This corresponds to the ``include_email`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -349,7 +358,7 @@ async def generate_id_token( sent along with the request as metadata. Returns: - ~.common.GenerateIdTokenResponse: + google.cloud.iam_credentials_v1.types.GenerateIdTokenResponse: """ # Create or coerce a protobuf request object. @@ -420,7 +429,7 @@ async def sign_blob( private key. Args: - request (:class:`~.common.SignBlobRequest`): + request (:class:`google.cloud.iam_credentials_v1.types.SignBlobRequest`): The request object. name (:class:`str`): Required. The resource name of the service account for @@ -429,6 +438,7 @@ async def sign_blob( ``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-`` wildcard character is required; replacing it with a project ID is invalid. + This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -446,6 +456,7 @@ async def sign_blob( ``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-`` wildcard character is required; replacing it with a project ID is invalid. + This corresponds to the ``delegates`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -462,7 +473,7 @@ async def sign_blob( sent along with the request as metadata. Returns: - ~.common.SignBlobResponse: + google.cloud.iam_credentials_v1.types.SignBlobResponse: """ # Create or coerce a protobuf request object. @@ -531,7 +542,7 @@ async def sign_jwt( private key. Args: - request (:class:`~.common.SignJwtRequest`): + request (:class:`google.cloud.iam_credentials_v1.types.SignJwtRequest`): The request object. name (:class:`str`): Required. The resource name of the service account for @@ -540,6 +551,7 @@ async def sign_jwt( ``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-`` wildcard character is required; replacing it with a project ID is invalid. + This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -557,6 +569,7 @@ async def sign_jwt( ``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-`` wildcard character is required; replacing it with a project ID is invalid. + This corresponds to the ``delegates`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -564,6 +577,7 @@ async def sign_jwt( Required. The JWT payload to sign: a JSON object that contains a JWT Claims Set. + This corresponds to the ``payload`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -575,7 +589,7 @@ async def sign_jwt( sent along with the request as metadata. Returns: - ~.common.SignJwtResponse: + google.cloud.iam_credentials_v1.types.SignJwtResponse: """ # Create or coerce a protobuf request object. diff --git a/google/cloud/iam_credentials_v1/services/iam_credentials/client.py b/google/cloud/iam_credentials_v1/services/iam_credentials/client.py index 4cd94d6..5614db4 100644 --- a/google/cloud/iam_credentials_v1/services/iam_credentials/client.py +++ b/google/cloud/iam_credentials_v1/services/iam_credentials/client.py @@ -121,6 +121,22 @@ def _get_default_mtls_endpoint(api_endpoint): DEFAULT_ENDPOINT ) + @classmethod + def from_service_account_info(cls, info: dict, *args, **kwargs): + """Creates an instance of this client using the provided credentials info. + + Args: + info (dict): The service account private key info. + args: Additional arguments to pass to the constructor. + kwargs: Additional arguments to pass to the constructor. + + Returns: + IAMCredentialsClient: The constructed client. + """ + credentials = service_account.Credentials.from_service_account_info(info) + kwargs["credentials"] = credentials + return cls(*args, **kwargs) + @classmethod def from_service_account_file(cls, filename: str, *args, **kwargs): """Creates an instance of this client using the provided credentials @@ -133,7 +149,7 @@ def from_service_account_file(cls, filename: str, *args, **kwargs): kwargs: Additional arguments to pass to the constructor. Returns: - {@api.name}: The constructed client. + IAMCredentialsClient: The constructed client. """ credentials = service_account.Credentials.from_service_account_file(filename) kwargs["credentials"] = credentials @@ -241,10 +257,10 @@ def __init__( credentials identify the application to the service; if none are specified, the client will attempt to ascertain the credentials from the environment. - transport (Union[str, ~.IAMCredentialsTransport]): The + transport (Union[str, IAMCredentialsTransport]): The transport to use. If set to None, a transport is chosen automatically. - client_options (client_options_lib.ClientOptions): Custom options for the + client_options (google.api_core.client_options.ClientOptions): Custom options for the client. It won't take effect if a ``transport`` instance is provided. (1) The ``api_endpoint`` property can be used to override the default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT @@ -358,19 +374,20 @@ def generate_access_token( account. Args: - request (:class:`~.common.GenerateAccessTokenRequest`): + request (google.cloud.iam_credentials_v1.types.GenerateAccessTokenRequest): The request object. - name (:class:`str`): + name (str): Required. The resource name of the service account for which the credentials are requested, in the following format: ``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-`` wildcard character is required; replacing it with a project ID is invalid. + This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this should not be set. - delegates (:class:`Sequence[str]`): + delegates (Sequence[str]): The sequence of service accounts in a delegation chain. Each service account must be granted the ``roles/iam.serviceAccountTokenCreator`` role on its @@ -384,26 +401,29 @@ def generate_access_token( ``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-`` wildcard character is required; replacing it with a project ID is invalid. + This corresponds to the ``delegates`` field on the ``request`` instance; if ``request`` is provided, this should not be set. - scope (:class:`Sequence[str]`): + scope (Sequence[str]): Required. Code to identify the scopes to be included in the OAuth 2.0 access token. See https://developers.google.com/identity/protocols/googlescopes for more information. At least one value required. + This corresponds to the ``scope`` field on the ``request`` instance; if ``request`` is provided, this should not be set. - lifetime (:class:`~.duration.Duration`): + lifetime (google.protobuf.duration_pb2.Duration): The desired lifetime duration of the access token in seconds. Must be set to a value less than or equal to 3600 (1 hour). If a value is not specified, the token's lifetime will be set to a default value of one hour. + This corresponds to the ``lifetime`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -415,7 +435,7 @@ def generate_access_token( sent along with the request as metadata. Returns: - ~.common.GenerateAccessTokenResponse: + google.cloud.iam_credentials_v1.types.GenerateAccessTokenResponse: """ # Create or coerce a protobuf request object. @@ -480,19 +500,20 @@ def generate_id_token( account. Args: - request (:class:`~.common.GenerateIdTokenRequest`): + request (google.cloud.iam_credentials_v1.types.GenerateIdTokenRequest): The request object. - name (:class:`str`): + name (str): Required. The resource name of the service account for which the credentials are requested, in the following format: ``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-`` wildcard character is required; replacing it with a project ID is invalid. + This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this should not be set. - delegates (:class:`Sequence[str]`): + delegates (Sequence[str]): The sequence of service accounts in a delegation chain. Each service account must be granted the ``roles/iam.serviceAccountTokenCreator`` role on its @@ -506,20 +527,23 @@ def generate_id_token( ``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-`` wildcard character is required; replacing it with a project ID is invalid. + This corresponds to the ``delegates`` field on the ``request`` instance; if ``request`` is provided, this should not be set. - audience (:class:`str`): + audience (str): Required. The audience for the token, such as the API or account that this token grants access to. + This corresponds to the ``audience`` field on the ``request`` instance; if ``request`` is provided, this should not be set. - include_email (:class:`bool`): + include_email (bool): Include the service account email in the token. If set to ``true``, the token will contain ``email`` and ``email_verified`` claims. + This corresponds to the ``include_email`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -531,7 +555,7 @@ def generate_id_token( sent along with the request as metadata. Returns: - ~.common.GenerateIdTokenResponse: + google.cloud.iam_credentials_v1.types.GenerateIdTokenResponse: """ # Create or coerce a protobuf request object. @@ -595,19 +619,20 @@ def sign_blob( private key. Args: - request (:class:`~.common.SignBlobRequest`): + request (google.cloud.iam_credentials_v1.types.SignBlobRequest): The request object. - name (:class:`str`): + name (str): Required. The resource name of the service account for which the credentials are requested, in the following format: ``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-`` wildcard character is required; replacing it with a project ID is invalid. + This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this should not be set. - delegates (:class:`Sequence[str]`): + delegates (Sequence[str]): The sequence of service accounts in a delegation chain. Each service account must be granted the ``roles/iam.serviceAccountTokenCreator`` role on its @@ -621,10 +646,11 @@ def sign_blob( ``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-`` wildcard character is required; replacing it with a project ID is invalid. + This corresponds to the ``delegates`` field on the ``request`` instance; if ``request`` is provided, this should not be set. - payload (:class:`bytes`): + payload (bytes): Required. The bytes to sign. This corresponds to the ``payload`` field on the ``request`` instance; if ``request`` is provided, this @@ -637,7 +663,7 @@ def sign_blob( sent along with the request as metadata. Returns: - ~.common.SignBlobResponse: + google.cloud.iam_credentials_v1.types.SignBlobResponse: """ # Create or coerce a protobuf request object. @@ -699,19 +725,20 @@ def sign_jwt( private key. Args: - request (:class:`~.common.SignJwtRequest`): + request (google.cloud.iam_credentials_v1.types.SignJwtRequest): The request object. - name (:class:`str`): + name (str): Required. The resource name of the service account for which the credentials are requested, in the following format: ``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-`` wildcard character is required; replacing it with a project ID is invalid. + This corresponds to the ``name`` field on the ``request`` instance; if ``request`` is provided, this should not be set. - delegates (:class:`Sequence[str]`): + delegates (Sequence[str]): The sequence of service accounts in a delegation chain. Each service account must be granted the ``roles/iam.serviceAccountTokenCreator`` role on its @@ -725,13 +752,15 @@ def sign_jwt( ``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-`` wildcard character is required; replacing it with a project ID is invalid. + This corresponds to the ``delegates`` field on the ``request`` instance; if ``request`` is provided, this should not be set. - payload (:class:`str`): + payload (str): Required. The JWT payload to sign: a JSON object that contains a JWT Claims Set. + This corresponds to the ``payload`` field on the ``request`` instance; if ``request`` is provided, this should not be set. @@ -743,7 +772,7 @@ def sign_jwt( sent along with the request as metadata. Returns: - ~.common.SignJwtResponse: + google.cloud.iam_credentials_v1.types.SignJwtResponse: """ # Create or coerce a protobuf request object. diff --git a/google/cloud/iam_credentials_v1/types/common.py b/google/cloud/iam_credentials_v1/types/common.py index 5da8235..eb8fa59 100644 --- a/google/cloud/iam_credentials_v1/types/common.py +++ b/google/cloud/iam_credentials_v1/types/common.py @@ -67,7 +67,7 @@ class GenerateAccessTokenRequest(proto.Message): https://developers.google.com/identity/protocols/googlescopes for more information. At least one value required. - lifetime (~.duration.Duration): + lifetime (google.protobuf.duration_pb2.Duration): The desired lifetime duration of the access token in seconds. Must be set to a value less than or equal to 3600 (1 hour). If a value is @@ -90,7 +90,7 @@ class GenerateAccessTokenResponse(proto.Message): Attributes: access_token (str): The OAuth 2.0 access token. - expire_time (~.timestamp.Timestamp): + expire_time (google.protobuf.timestamp_pb2.Timestamp): Token expiration time. The expiration time is always set. """ diff --git a/synth.metadata b/synth.metadata index b45ad4a..d684b50 100644 --- a/synth.metadata +++ b/synth.metadata @@ -4,15 +4,15 @@ "git": { "name": ".", "remote": "https://github.com/googleapis/python-iam.git", - "sha": "6e527955a3432ddafa20e303551f4a60b3e44baf" + "sha": "197a016688157a2b5350c612694a87b682009c8a" } }, { "git": { "name": "googleapis", "remote": "https://github.com/googleapis/googleapis.git", - "sha": "bdab50fe10ce3190812697e06f2e860780e9095e", - "internalRef": "347327128" + "sha": "520682435235d9c503983a360a2090025aa47cd1", + "internalRef": "350246057" } }, { @@ -87,6 +87,7 @@ "docs/_static/custom.css", "docs/_templates/layout.html", "docs/conf.py", + "docs/credentials_v1/iam_credentials.rst", "docs/credentials_v1/services.rst", "docs/credentials_v1/types.rst", "docs/multiprocessing.rst", diff --git a/tests/unit/gapic/credentials_v1/test_iam_credentials.py b/tests/unit/gapic/credentials_v1/test_iam_credentials.py index 28a89fb..ede64da 100644 --- a/tests/unit/gapic/credentials_v1/test_iam_credentials.py +++ b/tests/unit/gapic/credentials_v1/test_iam_credentials.py @@ -89,8 +89,21 @@ def test__get_default_mtls_endpoint(): ) +def test_iam_credentials_client_from_service_account_info(): + creds = credentials.AnonymousCredentials() + with mock.patch.object( + service_account.Credentials, "from_service_account_info" + ) as factory: + factory.return_value = creds + info = {"valid": True} + client = IAMCredentialsClient.from_service_account_info(info) + assert client.transport._credentials == creds + + assert client.transport._host == "iamcredentials.googleapis.com:443" + + @pytest.mark.parametrize( - "client_class", [IAMCredentialsClient, IAMCredentialsAsyncClient] + "client_class", [IAMCredentialsClient, IAMCredentialsAsyncClient,] ) def test_iam_credentials_client_from_service_account_file(client_class): creds = credentials.AnonymousCredentials() @@ -109,7 +122,10 @@ def test_iam_credentials_client_from_service_account_file(client_class): def test_iam_credentials_client_get_transport_class(): transport = IAMCredentialsClient.get_transport_class() - assert transport == transports.IAMCredentialsGrpcTransport + available_transports = [ + transports.IAMCredentialsGrpcTransport, + ] + assert transport in available_transports transport = IAMCredentialsClient.get_transport_class("grpc") assert transport == transports.IAMCredentialsGrpcTransport @@ -1527,7 +1543,7 @@ def test_iam_credentials_host_with_port(): def test_iam_credentials_grpc_transport_channel(): - channel = grpc.insecure_channel("http://localhost/") + channel = grpc.secure_channel("http://localhost/", grpc.local_channel_credentials()) # Check that channel is used if provided. transport = transports.IAMCredentialsGrpcTransport( @@ -1539,7 +1555,7 @@ def test_iam_credentials_grpc_transport_channel(): def test_iam_credentials_grpc_asyncio_transport_channel(): - channel = aio.insecure_channel("http://localhost/") + channel = aio.secure_channel("http://localhost/", grpc.local_channel_credentials()) # Check that channel is used if provided. transport = transports.IAMCredentialsGrpcAsyncIOTransport( @@ -1564,7 +1580,7 @@ def test_iam_credentials_transport_channel_mtls_with_client_cert_source( "grpc.ssl_channel_credentials", autospec=True ) as grpc_ssl_channel_cred: with mock.patch.object( - transport_class, "create_channel", autospec=True + transport_class, "create_channel" ) as grpc_create_channel: mock_ssl_cred = mock.Mock() grpc_ssl_channel_cred.return_value = mock_ssl_cred @@ -1617,7 +1633,7 @@ def test_iam_credentials_transport_channel_mtls_with_adc(transport_class): ssl_credentials=mock.PropertyMock(return_value=mock_ssl_cred), ): with mock.patch.object( - transport_class, "create_channel", autospec=True + transport_class, "create_channel" ) as grpc_create_channel: mock_grpc_channel = mock.Mock() grpc_create_channel.return_value = mock_grpc_channel