feat: adds user agent parameters to two functions

[chalmerlowe]

This adds:

• the ability for users to set a customer user agent (instead of the default user agent string that is currently hard coded in)
• docstrings and type hinting for the functions that we touched
• tests to test the new code path in google_client_info.

• Add tests to check various states/edge cases (TBD)

Fixes #1082 🦕

[conventional-commit-lint-gcf]

🤖 I detect that the PR title and the commit message differ and there's only one commit. To use the PR title for the commit history, you can use Github's automerge feature with squashing, or use automerge label. Good luck human!

-- conventional-commit-lint bot
https://conventionalcommits.org/

[Linchin]

NIT:

Looks like it should be string?

Suggested change

	user_agent (Optional[google.api_core.client_info.ClientInfo]):
	user_agent (Optional[str]):

[chalmerlowe]

This line is correct. The other line that had str was in error.

google_client_info returns a ClientInfo object which may include the user_agent string as well as several other attributes:

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
self.rest_version = rest_version

In addition, looking at the bigquery.Client object, it is expecting a ClientInfo object:

client_info (Optional[google.api_core.client_info.ClientInfo]):

[Linchin]

Just looking at the code, user_agent is passed to google_client_info(), which is expecting a string. google.api_core.client_info.ClientInfo seems to be what google_client_info() returns instead?

[Linchin]

LGTM. Just some thoughts: should we add a system test to verify that user agent is indeed successfully set up?

[chalmerlowe]

LGTM. Just some thoughts: should we add a system test to verify that user agent is indeed successfully set up?

I am not inclined to put the time/resources to add a system test to cover this minor update.

Right now, when the to_user_agent() method is called...the customer-supplied user agent string has a variety of elements appended to it. These elements are dynamic and change depending on the versions of certain components that are installed.

Are you picturing an end-to-end system test that accounts for each element of this string? If so, then that type of test feels like it may be brittle and would be dependent on exactly what sub-components are present in this function and might involve complex checks like regex. There might be ways to simplify the checks.

If you have alternate ideas on how to do this simply, easily, and in a way that is robust to change within the code, you are welcome to suggest something.

if self.grpc_version is not None:
    ua += "grpc/{grpc_version} "

if self.rest_version is not None:
    ua += "rest/{rest_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} "

[Linchin]

I will add a system test similar to the rest of tests in test_helpers.py. Sorry that I'm unable to suggest code change to locations unedited by this PR, apparently it's a feature request with github that hasn't been fulfilled. Feel free to modify as needed.