wip

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):

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/%namespace/%name_%version/%sub/services/%service/transports/_rest_mixins.py.j2

@@ -60,6 +60,10 @@
             # Jsonify the query params
             query_params = json.loads(json.dumps(transcoded_request['query_params']))
 
+            {% if service.version %}
+            query_params["$apiVersion"] = "{{ service.version }}"
+            {% endif %}
+
             # Send the request
             headers = dict(metadata)
             headers['Content-Type'] = 'application/json'

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

@@ -397,6 +397,10 @@ class {{service.name}}RestTransport({{service.name}}Transport):
             query_params["$alt"] = "json;enum-encoding=int"
             {% endif %}
 
+            {% if service.version %}
+            query_params["$apiVersion"] = "{{ service.version }}"
+            {% endif %}
+
             # Send the request
             headers = dict(metadata)
             headers['Content-Type'] = 'application/json'

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():

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()