feat: add support for reading google.api.api_version

Author: parthea

gapic/ads-templates/%namespace/%name/%version/%sub/services/%service/client.py.j2

@@ -94,7 +94,10 @@ class {{ service.client_name }}Meta(type):
 
 
 class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
-    """{{ service.meta.doc|rst(width=72, indent=4) }}"""
+    """{{ service.meta.doc|rst(width=72, indent=4) }}{% if service.version|length %}
+    This class implements API version {{ service.version }}."""
+    {% else %}"""
+    {% endif %}
 
     @staticmethod
     def _get_default_mtls_endpoint(api_endpoint):
@@ -476,6 +479,11 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
         )
         {% endif %}
 
+        {% if service.version %}
+        metadata = tuple(metadata) + (
+            gapic_v1.version_header.to_grpc_metadata("{{ service.version }}"),
+        )
+        {% endif %}
 {#
     Automatically populate UUID4 fields according to
     https://google.aip.dev/client-libraries/4235 when the

gapic/ads-templates/setup.py.j2

@@ -29,7 +29,8 @@ else:
     release_status = "Development Status :: 5 - Production/Stable"
 
 dependencies = [
-    "google-api-core[grpc] >= 2.10.0, < 3.0.0dev",
+    "google-api-core @ git+https://github.com/googleapis/python-api-core.git@add-api-version-header",
+    #"google-api-core[grpc] >= 2.10.0, < 3.0.0dev",
     "google-auth >= 2.14.1, <3.0.0dev",
     "googleapis-common-protos >= 1.53.0",
     "grpcio >= 1.10.0",

gapic/schema/wrappers.py

@@ -1734,6 +1734,17 @@ def host(self) -> str:
             return self.options.Extensions[client_pb2.default_host]
         return ''
 
+    @property
+    def version(self) -> str:
+        """Return the API version for this service, if specified.
+
+        Returns:
+            str: The API version for this service.
+        """
+        if self.options.Extensions[client_pb2.api_version]:
+            return self.options.Extensions[client_pb2.api_version]
+        return ''
+
     @property
     def shortname(self) -> str:
         """Return the API short name. DRIFT uses this to identify

gapic/templates/%namespace/%name_%version/%sub/services/%service/_client_macros.j2

@@ -183,6 +183,12 @@
         )
         {% endif %} {# method.explicit_routing #}
 
+        {% if service.version %}
+        metadata = tuple(metadata) + (
+            gapic_v1.version_header.to_grpc_metadata("{{ service.version }}"),
+        )
+        {% endif %}
+
 {{ auto_populate_uuid4_fields(api, method) }}
 
         # Validate the universe domain.

gapic/templates/%namespace/%name_%version/%sub/services/%service/async_client.py.j2

@@ -54,7 +54,10 @@ from .client import {{ service.client_name }}
 
 {# TODO(yon-mg): handle rest transport async client interaction #}
 class {{ service.async_client_name }}:
-    """{{ service.meta.doc|rst(width=72, indent=4) }}"""
+    """{{ service.meta.doc|rst(width=72, indent=4) }}{% if service.version|length %}
+    This class implements API version {{ service.version }}."""
+    {% else %}"""
+    {% endif %}
 
     _client: {{ service.client_name }}
 
@@ -388,6 +391,12 @@ class {{ service.async_client_name }}:
         )
         {% endif %}
 
+        {% if service.version %}
+        metadata = tuple(metadata) + (
+            gapic_v1.version_header.to_grpc_metadata("{{ service.version }}")
+        )
+        {% endif %}
+
 {{ macros.auto_populate_uuid4_fields(api, method) }}
 
         # Validate the universe domain.

gapic/templates/%namespace/%name_%version/%sub/services/%service/client.py.j2

@@ -102,7 +102,10 @@ class {{ service.client_name }}Meta(type):
 
 
 class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
-    """{{ service.meta.doc|rst(width=72, indent=4) }}"""
+    """{{ service.meta.doc|rst(width=72, indent=4) }}{% if service.version|length %}
+    This class implements API version {{ service.version }}."""
+    {% else %}"""
+    {% endif %}
 
     @staticmethod
     def _get_default_mtls_endpoint(api_endpoint):

gapic/templates/setup.py.j2

@@ -30,7 +30,8 @@ else:
     release_status = "Development Status :: 5 - Production/Stable"
 
 dependencies = [
-    "google-api-core[grpc] >= 1.34.1, <3.0.0dev,!=2.0.*,!=2.1.*,!=2.2.*,!=2.3.*,!=2.4.*,!=2.5.*,!=2.6.*,!=2.7.*,!=2.8.*,!=2.9.*,!=2.10.*",
+    "google-api-core @ git+https://github.com/googleapis/python-api-core.git@add-api-version-header",
+    #"google-api-core[grpc] >= 1.34.1, <3.0.0dev,!=2.0.*,!=2.1.*,!=2.2.*,!=2.3.*,!=2.4.*,!=2.5.*,!=2.6.*,!=2.7.*,!=2.8.*,!=2.9.*,!=2.10.*",
     # Exclude incompatible versions of `google-auth`
     # See https://github.com/googleapis/google-cloud-python/issues/12364
     "google-auth >= 2.14.1, <3.0.0dev,!=2.24.0,!=2.25.0",

gapic/templates/testing/_default_constraints.j2

@@ -1,7 +1,6 @@
 {% from '_pypi_packages.j2' import pypi_packages %}
 # This constraints file is required for unit tests.
 # List all library dependencies and extras in this file.
-google-api-core
 proto-plus
 protobuf
 {% for package_tuple, package_info in pypi_packages.items() %}

gapic/templates/testing/constraints-3.7.txt.j2

@@ -5,7 +5,6 @@
 # Pin the version to the lower bound.
 # e.g., if setup.py has "google-cloud-foo >= 1.14.0, < 2.0.0dev",
 # Then this file should have google-cloud-foo==1.14.0
-google-api-core==1.34.1
 google-auth==2.14.1
 proto-plus==1.22.3
 protobuf==3.19.5

gapic/templates/tests/unit/gapic/%name_%version/%sub/test_macros.j2

@@ -121,6 +121,29 @@ def test_{{ method_name }}(request_type, transport: str = 'grpc'):
     {% endif %}
     {% endwith %}{# auto_populated_field_sample_value #}
 
+{% if service.version %}
+{% for mode in ["", "async"] %}
+{% if mode == "async" %}
+async def test_{{ method_name }}_api_version_header_async(client={{ service.async_client_name }}()):
+{% else %}
+def test_{{ method_name }}_api_version_header(client={{ service.client_name }}()):
+{% endif %}
+    # Mock the actual call within the gRPC stub, and fake the request.
+    with mock.patch.object(
+            type(client.transport.{{ method.transport_safe_name|snake_case }}),
+            '__call__'
+        ) as call:
+        {% if mode == "async" %}
+            await client.{{ method_name }}()
+        {% else %}
+            client.{{ method_name }}()
+        {% endif %}
+
+    # Establish that the api version header was sent.
+    _, _, kw = call.mock_calls[0]
+    assert kw['metadata'][0] == (gapic_v1.version_header.API_VERSION_METADATA_KEY, "{{ service.version }}")
+{% endfor %}{# mode #}
+{% endif %}{# service.version #}
 
 {% if not method.client_streaming %}
 def test_{{ method_name }}_empty_call():

setup.py

@@ -28,7 +28,8 @@
     # Ensure that the lower bounds of these dependencies match what we have in the
     # templated setup.py.j2: https://github.com/googleapis/gapic-generator-python/blob/main/gapic/templates/setup.py.j2
     "click >= 6.7",
-    "google-api-core[grpc] >= 1.34.1, <3.0.0dev,!=2.0.*,!=2.1.*,!=2.2.*,!=2.3.*,!=2.4.*,!=2.5.*,!=2.6.*,!=2.7.*,!=2.8.*,!=2.9.*,!=2.10.*",
+    "google-api-core @ git+https://github.com/googleapis/python-api-core.git@add-api-version-header",
+    #"google-api-core[grpc] >= 1.34.1, <3.0.0dev,!=2.0.*,!=2.1.*,!=2.2.*,!=2.3.*,!=2.4.*,!=2.5.*,!=2.6.*,!=2.7.*,!=2.8.*,!=2.9.*,!=2.10.*",
     "googleapis-common-protos >= 1.55.0",
     "grpcio >= 1.24.3",
     # 2.11.0 is required which adds the `default` argument to `jinja-filters.map()`

test_utils/test_utils.py

@@ -32,6 +32,7 @@ def make_service(
     visible_resources: typing.Optional[
         typing.Mapping[str, wrappers.CommonResource]
     ] = None,
+    version: str = "",
 ) -> wrappers.Service:
     visible_resources = visible_resources or {}
     # Define a service descriptor, and set a host and oauth scopes if
@@ -40,6 +41,8 @@ def make_service(
     if host:
         service_pb.options.Extensions[client_pb2.default_host] = host
     service_pb.options.Extensions[client_pb2.oauth_scopes] = ','.join(scopes)
+    if version:
+        service_pb.options.Extensions[client_pb2.api_version] = version
 
     # Return a service object to test.
     return wrappers.Service(

tests/fragments/google/api/client.proto

@@ -96,4 +96,20 @@ extend google.protobuf.ServiceOptions {
   //     ...
   //   }
   string oauth_scopes = 1050;
+
+  // The API version of this service, which should be sent by version-aware
+  // clients to the service. This allows services to abide by the schema and
+  // behavior of the service at the time this API version was deployed.
+  // The format of the API version must be treated as opaque by clients.
+  // Services may use a format with an apparent structure, but clients must
+  // not rely on this to determine components within an API version, or attempt
+  // to construct other valid API versions. Note that this is for upcoming
+  // functionality and may not be implemented for all services.
+  //
+  // Example:
+  //
+  //   service Foo {
+  //     option (google.api.api_version) = "v1_20230821_preview";
+  //   }
+  string api_version = 525000001;
 }

tests/fragments/test_api_version.proto

@@ -0,0 +1,37 @@
+// Copyright (C) 2023  Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.fragment;
+
+import "google/protobuf/struct.proto";
+import "google/api/client.proto";
+
+service MyServiceWithVersion {
+  option (google.api.api_version) = "v1_20230601";
+  option (google.api.default_host) = "my.example.com";
+
+  rpc MyMethod(MethodRequest) returns (MethodResponse) {
+    option (google.api.method_signature) = "parameter";
+  }
+}
+
+message MethodRequest {
+  google.protobuf.Value parameter = 1;
+}
+
+message MethodResponse {
+  google.protobuf.Value result = 1;
+}

tests/unit/schema/wrappers/test_service.py

@@ -70,6 +70,14 @@ def test_service_host():
     service = make_service(host='thingdoer.googleapis.com')
     assert service.host == 'thingdoer.googleapis.com'
 
+def test_service_api_version_not_specified():
+    service = make_service(host='thingdoer.googleapis.com')
+    assert not service.version
+
+def test_service_api_version_exists():
+    service = make_service(host='thingdoer.googleapis.com', version="goose")
+    assert service.version == "goose"
+
 
 def test_service_no_host():
     service = make_service()