Refactor 'client_info' support. (#7849)
* Add 'user_agent' and 'extra_headers' properties to 'Connection'.
Deprecate the 'USER_AGENT' and '_EXTRA_HEADERS' class-level attributes.
* Add 'client_info' parameter to 'Connection' ctor.
* Implement 'Connection.user_agent' via its '_client_info'.
* Ensure 'X-Goog-API-Client' header is always passed.
* Create/use non-GAPIC-specific 'ClientInfo' class FBO HTTP/JSON clients.
Derive the existing GAPIC class from it.
diff --git a/google/api_core/client_info.py b/google/api_core/client_info.py
new file mode 100644
index 0000000..b196b7a
--- /dev/null
+++ b/google/api_core/client_info.py
@@ -0,0 +1,96 @@
+# Copyright 2017 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.
+
+"""Helpers for providing client information.
+
+Client information is used to send information about the calling client,
+such as the library and Python version, to API services.
+"""
+
+import platform
+
+import pkg_resources
+
+_PY_VERSION = platform.python_version()
+_API_CORE_VERSION = pkg_resources.get_distribution("google-api-core").version
+
+try:
+ _GRPC_VERSION = pkg_resources.get_distribution("grpcio").version
+except pkg_resources.DistributionNotFound: # pragma: NO COVER
+ _GRPC_VERSION = None
+
+
+class ClientInfo(object):
+ """Client information used to generate a user-agent for API calls.
+
+ This user-agent information is sent along with API calls to allow the
+ receiving service to do analytics on which versions of Python and Google
+ libraries are being used.
+
+ Args:
+ python_version (str): The Python interpreter version, for example,
+ ``'2.7.13'``.
+ grpc_version (Optional[str]): The gRPC library version.
+ api_core_version (str): The google-api-core library version.
+ gapic_version (Optional[str]): The sversion of gapic-generated client
+ library, if the library was generated by gapic.
+ client_library_version (Optional[str]): The version of the client
+ library, generally used if the client library was not generated
+ by gapic or if additional functionality was built on top of
+ a gapic client library.
+ user_agent (Optional[str]): Prefix to the user agent header. This is
+ used to supply information such as application name or partner tool.
+ Recommended format: ``application-or-tool-ID/major.minor.version``.
+ """
+
+ def __init__(
+ self,
+ python_version=_PY_VERSION,
+ grpc_version=_GRPC_VERSION,
+ api_core_version=_API_CORE_VERSION,
+ gapic_version=None,
+ client_library_version=None,
+ user_agent=None,
+ ):
+ self.python_version = python_version
+ self.grpc_version = grpc_version
+ self.api_core_version = api_core_version
+ self.gapic_version = gapic_version
+ self.client_library_version = client_library_version
+ self.user_agent = user_agent
+
+ def to_user_agent(self):
+ """Returns the user-agent string for this client info."""
+
+ # Note: the order here is important as the internal metrics system
+ # expects these items to be in specific locations.
+ ua = ""
+
+ if self.user_agent is not None:
+ ua += "{user_agent} "
+
+ ua += "gl-python/{python_version} "
+
+ if self.grpc_version is not None:
+ ua += "grpc/{grpc_version} "
+
+ ua += "gax/{api_core_version} "
+
+ if self.gapic_version is not None:
+ ua += "gapic/{gapic_version} "
+
+ if self.client_library_version is not None:
+ ua += "gccl/{client_library_version} "
+
+ return ua.format(**self.__dict__).strip()
diff --git a/google/api_core/gapic_v1/client_info.py b/google/api_core/gapic_v1/client_info.py
index 069e019..bdc2ce4 100644
--- a/google/api_core/gapic_v1/client_info.py
+++ b/google/api_core/gapic_v1/client_info.py
@@ -18,22 +18,13 @@
such as the library and Python version, to API services.
"""
-import platform
+from google.api_core import client_info
-import pkg_resources
-
-_PY_VERSION = platform.python_version()
-_API_CORE_VERSION = pkg_resources.get_distribution("google-api-core").version
-
-try:
- _GRPC_VERSION = pkg_resources.get_distribution("grpcio").version
-except pkg_resources.DistributionNotFound: # pragma: NO COVER
- _GRPC_VERSION = None
METRICS_METADATA_KEY = "x-goog-api-client"
-class ClientInfo(object):
+class ClientInfo(client_info.ClientInfo):
"""Client information used to generate a user-agent for API calls.
This user-agent information is sent along with API calls to allow the
@@ -56,47 +47,6 @@
Recommended format: ``application-or-tool-ID/major.minor.version``.
"""
- def __init__(
- self,
- python_version=_PY_VERSION,
- grpc_version=_GRPC_VERSION,
- api_core_version=_API_CORE_VERSION,
- gapic_version=None,
- client_library_version=None,
- user_agent=None,
- ):
- self.python_version = python_version
- self.grpc_version = grpc_version
- self.api_core_version = api_core_version
- self.gapic_version = gapic_version
- self.client_library_version = client_library_version
- self.user_agent = user_agent
-
- def to_user_agent(self):
- """Returns the user-agent string for this client info."""
-
- # Note: the order here is important as the internal metrics system
- # expects these items to be in specific locations.
- ua = ""
-
- if self.user_agent is not None:
- ua += "{user_agent} "
-
- ua += "gl-python/{python_version} "
-
- if self.grpc_version is not None:
- ua += "grpc/{grpc_version} "
-
- ua += "gax/{api_core_version} "
-
- if self.gapic_version is not None:
- ua += "gapic/{gapic_version} "
-
- if self.client_library_version is not None:
- ua += "gccl/{client_library_version} "
-
- return ua.format(**self.__dict__).strip()
-
def to_grpc_metadata(self):
"""Returns the gRPC metadata for this client info."""
return (METRICS_METADATA_KEY, self.to_user_agent())
diff --git a/tests/unit/gapic/test_client_info.py b/tests/unit/gapic/test_client_info.py
index 0cca479..64080ff 100644
--- a/tests/unit/gapic/test_client_info.py
+++ b/tests/unit/gapic/test_client_info.py
@@ -16,59 +16,6 @@
from google.api_core.gapic_v1 import client_info
-def test_constructor_defaults():
- info = client_info.ClientInfo()
-
- assert info.python_version is not None
- assert info.grpc_version is not None
- assert info.api_core_version is not None
- assert info.gapic_version is None
- assert info.client_library_version is None
-
-
-def test_constructor_options():
- info = client_info.ClientInfo(
- python_version="1",
- grpc_version="2",
- api_core_version="3",
- gapic_version="4",
- client_library_version="5",
- user_agent="6"
- )
-
- assert info.python_version == "1"
- assert info.grpc_version == "2"
- assert info.api_core_version == "3"
- assert info.gapic_version == "4"
- assert info.client_library_version == "5"
- assert info.user_agent == "6"
-
-
-def test_to_user_agent_minimal():
- info = client_info.ClientInfo(
- python_version="1", api_core_version="2", grpc_version=None
- )
-
- user_agent = info.to_user_agent()
-
- assert user_agent == "gl-python/1 gax/2"
-
-
-def test_to_user_agent_full():
- info = client_info.ClientInfo(
- python_version="1",
- grpc_version="2",
- api_core_version="3",
- gapic_version="4",
- client_library_version="5",
- user_agent="app-name/1.0",
- )
-
- user_agent = info.to_user_agent()
-
- assert user_agent == "app-name/1.0 gl-python/1 grpc/2 gax/3 gapic/4 gccl/5"
-
-
def test_to_grpc_metadata():
info = client_info.ClientInfo()
diff --git a/tests/unit/test_client_info.py b/tests/unit/test_client_info.py
new file mode 100644
index 0000000..0eb17c5
--- /dev/null
+++ b/tests/unit/test_client_info.py
@@ -0,0 +1,69 @@
+# Copyright 2017 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.
+
+
+from google.api_core import client_info
+
+
+def test_constructor_defaults():
+ info = client_info.ClientInfo()
+
+ assert info.python_version is not None
+ assert info.grpc_version is not None
+ assert info.api_core_version is not None
+ assert info.gapic_version is None
+ assert info.client_library_version is None
+
+
+def test_constructor_options():
+ info = client_info.ClientInfo(
+ python_version="1",
+ grpc_version="2",
+ api_core_version="3",
+ gapic_version="4",
+ client_library_version="5",
+ user_agent="6"
+ )
+
+ assert info.python_version == "1"
+ assert info.grpc_version == "2"
+ assert info.api_core_version == "3"
+ assert info.gapic_version == "4"
+ assert info.client_library_version == "5"
+ assert info.user_agent == "6"
+
+
+def test_to_user_agent_minimal():
+ info = client_info.ClientInfo(
+ python_version="1", api_core_version="2", grpc_version=None
+ )
+
+ user_agent = info.to_user_agent()
+
+ assert user_agent == "gl-python/1 gax/2"
+
+
+def test_to_user_agent_full():
+ info = client_info.ClientInfo(
+ python_version="1",
+ grpc_version="2",
+ api_core_version="3",
+ gapic_version="4",
+ client_library_version="5",
+ user_agent="app-name/1.0",
+ )
+
+ user_agent = info.to_user_agent()
+
+ assert user_agent == "app-name/1.0 gl-python/1 grpc/2 gax/3 gapic/4 gccl/5"