diff --git a/.librarian/generator-input/client-post-processing/bigquery-storage-integration.yaml b/.librarian/generator-input/client-post-processing/bigquery-storage-integration.yaml index 3d42dc5822e0..9ae7cf942bc0 100644 --- a/.librarian/generator-input/client-post-processing/bigquery-storage-integration.yaml +++ b/.librarian/generator-input/client-post-processing/bigquery-storage-integration.yaml @@ -508,11 +508,5 @@ replacements: bigquery_storage_v1beta2/types_ bigquery_storage_v1alpha/services_ bigquery_storage_v1alpha/types_\n\n - Migration Guide - ---------------\n - See the guide below for instructions on migrating to the 2.x release of this library.\n - .. toctree:: - :maxdepth: 2\n - UPGRADING\n Changelog count: 1 diff --git a/packages/google-cloud-bigquery-storage/UPGRADING.md b/packages/google-cloud-bigquery-storage/UPGRADING.md deleted file mode 100644 index ef35b962a32a..000000000000 --- a/packages/google-cloud-bigquery-storage/UPGRADING.md +++ /dev/null @@ -1,284 +0,0 @@ - - - -# 2.0.0 Migration Guide - -The 2.0 release of the `google-cloud-bigquery-storage` client is a significant -upgrade based on a [next-gen code generator](https://github.com/googleapis/gapic-generator-python), -and includes substantial interface changes. Existing code written for earlier versions -of this library will likely require updates to use this version. This document -describes the changes that have been made, and what you need to do to update your usage. - -If you experience issues or have questions, please file an -[issue](https://github.com/googleapis/python-bigquery-storage/issues). - - -## Supported Python Versions - -> **WARNING**: Breaking change - -The 2.0.0 release requires Python 3.6+. - - -## Import Path - -The library's top-level namespace is `google.cloud.bigquery_storage`. Importing -from `google.cloud.bigquery_storage_v1` still works, but it is advisable to use -the `google.cloud.bigquery_storage` path in order to reduce the chance of future -compatibility issues should the library be restuctured internally. - -**Before:** -```py -from google.cloud.bigquery_storage_v1 import BigQueryReadClient -``` - -**After:** -```py -from google.cloud.bigquery_storage import BigQueryReadClient -``` - - -## Enum Types - -> **WARNING**: Breaking change - -Enum types have been moved. Access them through the `types` module. - -**Before:** -```py -from google.cloud.bigquery_storage_v1 import enums - -data_format = enums.DataFormat.ARROW -``` - -data_format = BigQueryReadClient.enums.DataFormat.ARROW - -**After:** -```py -from google.cloud.bigquery_storage import types - -data_format = types.DataFormat.ARROW -``` - -Additionally, enums cannot be accessed through the client anymore. The following -code wil _not_ work: -```py -data_format = BigQueryReadClient.enums.DataFormat.ARROW -``` - - -## Clients for Beta APIs - -> **WARNING**: Breaking change - -Clients for beta APIs have been removed. The following import will _not_ work: - -```py -from google.cloud.bigquery_storage_v1beta1 import BigQueryStorageClient -from google.cloud.bigquery_storage_v1beta2.gapic.big_query_read_client import BigQueryReadClient -``` - -The beta APIs are still available on the server side, but you will need to use -the 1.x version of the library to access them. - - -## Changed Default Value of the `read_rows()` Method's `metadata` Argument - -The `client.read_rows()` method does not accept `None` anymore as a valid value -for the optional `metadata` argument. If not given, an empty tuple is used, but -if you want to explicitly pass an "empty" value, you should use an empty tuple, too. - -**Before:** -```py -client.read_rows("stream_name", metadata=None) -``` - -**After:** -```py -client.read_rows("stream_name", metadata=()) -``` - -OR - -```py -client.read_rows("stream_name") -``` - - -## Method Calls - -> **WARNING**: Breaking change - -Most of the client methods that send requests to the backend expect request objects. -We provide a script that will convert most common use cases. - -> One exception to this is the `BigQueryReadClient.read_rows()` which is a hand-written -wrapper around the auto-generated `read_rows()` method. - -* Install the library - -```py -python3 -m pip install google-cloud-bigquery-storage -``` - -* The script `fixup_bigquery_storage_v1_keywords.py` is shipped with the library. It -requires `libcst` to be installed. It expects an input directory (with the code -to convert) and an empty destination directory. - -```sh -$ fixup_bigquery_storage_v1_keywords.py --input-directory .samples/ --output-directory samples/ -``` - -**Before:** -```py -from google.cloud import bigquery_storage_v1 - -client = bigquery_storage_v1.BigQueryReadClient() - -requested_session = bigquery_storage_v1.types.ReadSession() -requested_session.table = "projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID" -requested_session.data_format = bigquery_storage_v1.enums.DataFormat.ARROW - -session = client.create_read_session( - "projects/parent_project", - requested_session, - max_stream_count=1, -) -``` - -**After:** -```py -from google.cloud import bigquery_storage - -client = bigquery_storage.BigQueryReadClient() - -requested_session = bigquery_storage.types.ReadSession( - table="projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID", - data_format=bigquery_storage.types.DataFormat.ARROW, -) -session = client.create_read_session( - request={ - "parent": "projects/parent_project", - "read_session": requested_session, - "max_stream_count" 1, - }, -) -``` - -### More Details - -In `google-cloud-bigquery-storage<2.0.0`, parameters required by the API were positional -parameters and optional parameters were keyword parameters. - -**Before:** -```py -def create_read_session( - self, - parent, - read_session, - max_stream_count=None, - retry=google.api_core.gapic_v1.method.DEFAULT, - timeout=google.api_core.gapic_v1.method.DEFAULT, - metadata=None, -): -``` - -In the `2.0.0` release, methods that interact with the backend have a single -positional parameter `request`. Method docstrings indicate whether a parameter is -required or optional. - -Some methods have additional keyword only parameters. The available parameters depend -on the [`google.api.method_signature` annotation](https://github.com/googleapis/python-bigquery-storage/blob/9e1bf910e6f5010f479cf4592e25c3b3eebb456d/google/cloud/bigquery_storage_v1/proto/storage.proto#L73) -specified by the API producer. - - -**After:** -```py -def create_read_session( - self, - request: storage.CreateReadSessionRequest = None, - *, - parent: str = None, - read_session: stream.ReadSession = None, - max_stream_count: int = None, - retry: retries.Retry = gapic_v1.method.DEFAULT, - timeout: float = None, - metadata: Sequence[Tuple[str, str]] = (), -) -> stream.ReadSession: -``` - -> **NOTE:** The `request` parameter and flattened keyword parameters for the API are -> mutually exclusive. Passing both will result in an error. - -Both of these calls are valid: - -```py -session = client.create_read_session( - request={ - "parent": "projects/parent_project", - "read_session": requested_session, - "max_stream_count" 1, - }, -) -``` - -```py -response = client.create_read_session( - parent="projects/parent_project", - read_session=requested_session, - max_stream_count=1, -) -``` - -This call is _invalid_ because it mixes `request` with a keyword argument -`max_stream_count`. Executing this code will result in an error: - -```py -session = client.create_read_session( - request={ - "parent": "projects/parent_project", - "read_session": requested_session, - }, - max_stream_count=1, -) -``` - -> **NOTE:** The `request` parameter of some methods can also contain a more rich set of -> options that are otherwise not available as explicit keyword only parameters, thus -> these _must_ be passed through `request`. - - -## Removed Utility Methods - -> **WARNING**: Breaking change - -Several utility methods such as `project_path()` and `table_path()` have been removed. -These paths must now be constructed manually: - -```py -project_path = f"project/{PROJECT_ID}" -table_path = f"projects/{PROJECT_ID}/datasets/{DATASET_ID}/tables/{TABLE_ID}" -``` - -The two that remained are `read_session_path()` and `read_stream_path()`. - - -## Removed `client_config` and `channel` Parameter - -The client cannot be constructed with `channel` or `client_config` arguments anymore, -these deprecated parameters have been removed. - -If you used `client_config` to customize retry and timeout settings for a particular -method, you now need to do it upon method invocation by passing the custom `timeout` and -`retry` arguments, respectively. diff --git a/packages/google-cloud-bigquery-storage/docs/UPGRADING.md b/packages/google-cloud-bigquery-storage/docs/UPGRADING.md deleted file mode 120000 index 01097c8c0fb8..000000000000 --- a/packages/google-cloud-bigquery-storage/docs/UPGRADING.md +++ /dev/null @@ -1 +0,0 @@ -../UPGRADING.md \ No newline at end of file diff --git a/packages/google-cloud-bigquery-storage/docs/index.rst b/packages/google-cloud-bigquery-storage/docs/index.rst index 32842c27fc7c..87b0642dbe00 100644 --- a/packages/google-cloud-bigquery-storage/docs/index.rst +++ b/packages/google-cloud-bigquery-storage/docs/index.rst @@ -30,16 +30,6 @@ API Reference bigquery_storage_v1alpha/types_ -Migration Guide ---------------- - -See the guide below for instructions on migrating to the 2.x release of this library. - -.. toctree:: - :maxdepth: 2 - - UPGRADING - Changelog --------- diff --git a/packages/google-cloud-dialogflow/UPGRADING.md b/packages/google-cloud-dialogflow/UPGRADING.md deleted file mode 100644 index aa2609dd0c44..000000000000 --- a/packages/google-cloud-dialogflow/UPGRADING.md +++ /dev/null @@ -1,251 +0,0 @@ -# 2.0.0 Migration Guide - -The 2.0 release of the `google-cloud-dialogflow` client is a significant upgrade based on a [next-gen code generator](https://github.com/googleapis/gapic-generator-python), and includes substantial interface changes. Existing code written for earlier versions of this library will likely require updates to use this version. This document describes the changes that have been made, and what you need to do to update your usage. - -If you experience issues or have questions, please file an [issue](https://github.com/googleapis/python-dialogflow/issues). - - -## Package import and naming -> **WARNING**: Breaking change - -The 2.0.0 release changes the name and import path of the library to fall under the google-cloud namespace. - -No further updates will be made to the package [dialogflow](https://pypi.org/project/dialogflow/) on PyPI. - -**Before:** - -```sh -python3 -m pip install dialogflow -``` - -```py -import dialogflow -``` - -**After:** - -```sh -python3 -m pip install google-cloud-dialogflow -``` - -```py -from google.cloud import dialogflow -``` - - -## Supported Python Versions -> **WARNING**: Breaking change - -The 2.0.0 release requires Python 3.6+. - -## Method Calls -> **WARNING**: Breaking change - -Methods expect request objects. We provide a script that will convert most common use cases. - -* Install the library -```sh -$ python3 -m pip install google-cloud-dialogflow -``` -* The scripts `fixup_dialogflow_v2_keywords.py` and `fixup_dialogflow_v2beta1_keywords.py` are shipped with the library. It expects an input directory (with the code to convert) and an empty destination directory. - -```sh -$ fixup_dialogflow_v2_keywords.py --input-directory .samples/ --output-directory samples/ -``` -**Before:** - -```py -import dialogflow -client = dialogflow.ContextsClient() - -response = client.list_contexts(parent="projects/1337/agent/sessions/1024") -``` - -**After:** -```py -from google.cloud import dialogflow - -client = dialogflow.ContextsClient() - -response = client.list_contexts(request={"parent": "projects/1337/agent/sessions/1024", page_size=10}) -``` - -### More Details -In google-cloud-dialogflow<2.0.0, parameters required by the API were positional parameters and optional parameters were keyword parameters. - -**Before:** -```py - def detect_intent( - self, - session, - query_input, - query_params=None, - output_audio_config=None, - output_audio_config_mask=None, - input_audio=None, - retry=google.api_core.gapic_v1.method.DEFAULT, - timeout=google.api_core.gapic_v1.method.DEFAULT, - metadata=None, - ): -``` - -In the 2.0.0 release, all methods have a single positional parameter request. Method docstrings indicate whether a parameter is required or optional. - -Some methods have additional keyword only parameters. The available parameters depend on the [`google.api.method_signature` annotation](https://github.com/googleapis/googleapis/blob/master/google/cloud/translate/v3/translation_service.proto#L55) specified by the API producer. - -**After:**: -```py - def detect_intent(self, - request=None, - *, - session: str=None, - query_input=None, - retry=gapic_v1.method.DEFAULT, - timeout=None, - metadata=(), - ): -``` - -> **NOTE:** The `request` parameter and flattened keyword parameters for the API are mutually exclusive. Passing both will result in an error. - -Both of these calls are valid: -```py -response = client.create_context( - request={ - "parent": "parent_value", - "context": dialogflow.Context(name="name_value"), - } -) -response = client.create_context( - parent="parent_value", - context=dialogflow.Context(name="name_value"), -) -``` - -This call is invalid because it mixes `request` with a keyword argument `audio_config`. Executing this code will result in an error. - -```py -response = client.create_context( - request={ - "parent": "parent_value", - }, - context=dialogflow.Context(name="name_value"), -) -``` - -## Enums and Types - -> **WARNING:** Breaking change - -The submodules `enums` and `types` have been removed in the versionless module. - -**Before:** - -```py -import dialogflow - -encoding = dialogflow.enums.AudioEncoding.AUDIO_ENCODING_FLAC -query_params = dialogflow.types.QueryParameters(time_zone="Europe/Paris") -``` - -**After:** - -```py -from google.cloud import dialogflow - -encoding = dialogflow.AudioEncoding.AUDIO_ENCODING_FLAC -query_params = dialogflow.QueryParameters(time_zone="Europe/Paris") -``` - -The `types` submodule is still present in the versioned module. - -E.g. - -```py -from google.cloud import dialogflow_v2 - -query_params = dialogflow_v2.types.QueryParameters(time_zone="Europe/Paris") -``` - - -## Resource path helpers - -> **WARNING**: Breaking change - -Some resource path helpers have been renamed, and others have been removed. -See below for an alternative method or a string. - - -**v2** -```py -from google.cloud import dialogflow_v2 - -# AgentsClient -project_path = dialogflow_v2.AgentsClient.common_project_path("PROJECT") - -# ContextsClient -session_path = dialogflow_v2.SessionsClient.session_path("PROJECT", "SESSION") - -# EntityTypesClient -agent_path = dialogflow_v2.AgentsClient.agent_path("PROJECT") -project_agent_path = dialogflow_v2.AgentsClient.agent_path("PROJECT") - -# EnvironmentsClient -agent_path = dialogflow_v2.AgentsClient.agent_path("PROJECT") - -# IntentsClient -agent_path = dialogflow_v2.AgentsClient.agent_path("PROJECT") -project_agent_path = dialogflow_v2.AgentsClient.agent_path("PROJECT") - -# SessionEntityTypesClient -session_path = dialogflow_v2.SessionsClient.session_path("PROJECT", "SESSION") - -``` - -**v2beta1** - -```py -from google.cloud import dialogflow_v2beta1 - -context = "CONTEXT" -entity_type = "ENTITY_TYPE" -environmnent = "ENVIRONMENT" -project = "PROJECT" -session = "SESSION" -user = "USER" - -# AgentsClient -location_path = dialogflow_v2beta1.AgentsClient.common_location_path( - "PROJECT", "LOCATION" -) -project_path = dialogflow_v2beta1.AgentsClient.common_project_path("PROJECT") - -# ContextsClient -environment_context_path = f"projects/{project}/agent/environments/{environment}/users/{user}/sessions/{session}/contexts/{context}" -environment_session_path = f"projects/{project}/agent/environments/{environment}/users/{user}/sessions/{session}" -session_path = dialogflow_v2beta1.SessionsClient.session_path("PROJECT", "SESSION") - -# DocumentsClient -knowledge_base_path = dialogflow_v2beta1.KnowledgeBasesClient.knowledge_base_path( - "PROJECT", "KNOWLEDGE_BASE" -) - -# EnvironmentsClient -agent_path = dialogflow_v2beta1.AgentsClient.agent_path("PROJECT") - -# IntentsClient -agent_path = dialogflow_v2beta1.AgentsClient.agent_path("PROJECT") -project_path = dialogflow_v2beta1.AgentsClient.common_project_path("PROJECT") - -# KnowledgeBasesClient -project_path = dialogflow_v2beta1.KnowledgeBasesClient.common_project_path("PROJECT") - -# SessionEntityTypesClient -environment_session_path = f"projects/{project}/agent/environments/{environment}/users/{user}/sessions/{session}" -environment_sessions_entity_path = f"projects/{project}/agent/environments/{environment}/users/{user}/sessions/{session}/entityTypes/{entity_type}" -session_path = f"projects/{project}/agent/sessions/{session}" - - -# SessionsClient -environment_session_path = f"projects/{project}/agent/environments/{environment}/users/{user}/sessions/{session}" -``` diff --git a/packages/google-cloud-texttospeech/samples/snippets/.gitignore b/packages/google-cloud-texttospeech/samples/snippets/.gitignore deleted file mode 100644 index 8f6514bdc379..000000000000 --- a/packages/google-cloud-texttospeech/samples/snippets/.gitignore +++ /dev/null @@ -1 +0,0 @@ -output.mp3 \ No newline at end of file diff --git a/packages/google-cloud-texttospeech/samples/snippets/README.md b/packages/google-cloud-texttospeech/samples/snippets/README.md deleted file mode 100644 index 9b4b465055b5..000000000000 --- a/packages/google-cloud-texttospeech/samples/snippets/README.md +++ /dev/null @@ -1,4 +0,0 @@ -Samples migrated -================ - -New location: https://github.com/GoogleCloudPlatform/python-docs-samples/tree/main/texttospeech diff --git a/packages/google-cloud-texttospeech/scripts/fixup_keywords.py b/packages/google-cloud-texttospeech/scripts/fixup_keywords.py deleted file mode 100644 index c216d0bad6d9..000000000000 --- a/packages/google-cloud-texttospeech/scripts/fixup_keywords.py +++ /dev/null @@ -1,178 +0,0 @@ -# -*- coding: utf-8 -*- - -# Copyright 2020 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. -# - -import argparse -import os -import libcst as cst -import pathlib -import sys -from typing import (Any, Callable, Dict, List, Sequence, Tuple) - - -def partition( - predicate: Callable[[Any], bool], - iterator: Sequence[Any] -) -> Tuple[List[Any], List[Any]]: - """A stable, out-of-place partition.""" - results = ([], []) - - for i in iterator: - results[int(predicate(i))].append(i) - - # Returns trueList, falseList - return results[1], results[0] - - -class texttospeechCallTransformer(cst.CSTTransformer): - CTRL_PARAMS: Tuple[str] = ('retry', 'timeout', 'metadata') - METHOD_TO_PARAMS: Dict[str, Tuple[str]] = { - 'list_voices': ('language_code', ), - 'synthesize_speech': ('input', 'voice', 'audio_config', ), - } - - def leave_Call(self, original: cst.Call, updated: cst.Call) -> cst.CSTNode: - try: - key = original.func.attr.value - kword_params = self.METHOD_TO_PARAMS[key] - except (AttributeError, KeyError): - # Either not a method from the API or too convoluted to be sure. - return updated - - # If the existing code is valid, keyword args come after positional args. - # Therefore, all positional args must map to the first parameters. - args, kwargs = partition(lambda a: not bool(a.keyword), updated.args) - if any(k.keyword.value == "request" for k in kwargs): - # We've already fixed this file, don't fix it again. - return updated - - kwargs, ctrl_kwargs = partition( - lambda a: not a.keyword.value in self.CTRL_PARAMS, - kwargs - ) - - args, ctrl_args = args[:len(kword_params)], args[len(kword_params):] - ctrl_kwargs.extend(cst.Arg(value=a.value, keyword=cst.Name(value=ctrl)) - for a, ctrl in zip(ctrl_args, self.CTRL_PARAMS)) - - request_arg = cst.Arg( - value=cst.Dict([ - cst.DictElement( - cst.SimpleString("'{}'".format(name)), - cst.Element(value=arg.value) - ) - # Note: the args + kwargs looks silly, but keep in mind that - # the control parameters had to be stripped out, and that - # those could have been passed positionally or by keyword. - for name, arg in zip(kword_params, args + kwargs)]), - keyword=cst.Name("request") - ) - - return updated.with_changes( - args=[request_arg] + ctrl_kwargs - ) - - -def fix_files( - in_dir: pathlib.Path, - out_dir: pathlib.Path, - *, - transformer=texttospeechCallTransformer(), -): - """Duplicate the input dir to the output dir, fixing file method calls. - - Preconditions: - * in_dir is a real directory - * out_dir is a real, empty directory - """ - pyfile_gen = ( - pathlib.Path(os.path.join(root, f)) - for root, _, files in os.walk(in_dir) - for f in files if os.path.splitext(f)[1] == ".py" - ) - - for fpath in pyfile_gen: - with open(fpath, 'r') as f: - src = f.read() - - # Parse the code and insert method call fixes. - tree = cst.parse_module(src) - updated = tree.visit(transformer) - - # Create the path and directory structure for the new file. - updated_path = out_dir.joinpath(fpath.relative_to(in_dir)) - updated_path.parent.mkdir(parents=True, exist_ok=True) - - # Generate the updated source file at the corresponding path. - with open(updated_path, 'w') as f: - f.write(updated.code) - - -if __name__ == '__main__': - parser = argparse.ArgumentParser( - description="""Fix up source that uses the texttospeech client library. - -The existing sources are NOT overwritten but are copied to output_dir with changes made. - -Note: This tool operates at a best-effort level at converting positional - parameters in client method calls to keyword based parameters. - Cases where it WILL FAIL include - A) * or ** expansion in a method call. - B) Calls via function or method alias (includes free function calls) - C) Indirect or dispatched calls (e.g. the method is looked up dynamically) - - These all constitute false negatives. The tool will also detect false - positives when an API method shares a name with another method. -""") - parser.add_argument( - '-d', - '--input-directory', - required=True, - dest='input_dir', - help='the input directory to walk for python files to fix up', - ) - parser.add_argument( - '-o', - '--output-directory', - required=True, - dest='output_dir', - help='the directory to output files fixed via un-flattening', - ) - args = parser.parse_args() - input_dir = pathlib.Path(args.input_dir) - output_dir = pathlib.Path(args.output_dir) - if not input_dir.is_dir(): - print( - f"input directory '{input_dir}' does not exist or is not a directory", - file=sys.stderr, - ) - sys.exit(-1) - - if not output_dir.is_dir(): - print( - f"output directory '{output_dir}' does not exist or is not a directory", - file=sys.stderr, - ) - sys.exit(-1) - - if os.listdir(output_dir): - print( - f"output directory '{output_dir}' is not empty", - file=sys.stderr, - ) - sys.exit(-1) - - fix_files(input_dir, output_dir) diff --git a/packages/google-cloud-texttospeech/testing/secrets.tar.enc b/packages/google-cloud-texttospeech/testing/secrets.tar.enc deleted file mode 100644 index 1a749dbfcc0d..000000000000 Binary files a/packages/google-cloud-texttospeech/testing/secrets.tar.enc and /dev/null differ diff --git a/packages/google-cloud-trace/UPGRADING.md b/packages/google-cloud-trace/UPGRADING.md deleted file mode 100644 index 5006232e56d8..000000000000 --- a/packages/google-cloud-trace/UPGRADING.md +++ /dev/null @@ -1,162 +0,0 @@ -# 1.0.0 Migration Guide - -The 1.0 release of the `google-cloud-trace` client is a significant upgrade based on a [next-gen code generator](https://github.com/googleapis/gapic-generator-python), and includes substantial interface changes. Existing code written for earlier versions of this library will likely require updates to use this version. This document describes the changes that have been made, and what you need to do to update your usage. - -If you experience issues or have questions, please file an [issue](https://github.com/googleapis/python-trace/issues). - -## Supported Python Versions - -> **WARNING**: Breaking change - -The 1.0.0 release requires Python 3.6+. - - -## Handwritten Client Wrapper Removal - -The handwritten client wrapper `trace_v1.Client()` and `trace_v2.Client()` have been removed. Please use `TraceServiceClient` directly. The primary diference is that a `project_id` must always be supplied to method calls. - - -```py -from google.cloud import trace_v1 - -client = trace_v1.TraceServiceClient() -``` - -```py -from google.cloud import trace_v2 - -client = trace_v2.TraceServiceClient() -``` - -**NOTE**: The following sections identify changes between the previous `TraceServiceClient()` and the current `TraceServiceClient()` (not the handwritten wrapper `Client()`). If you were previously using `Client()`, it may be more helpful to reference the [samples](https://github.com/googleapis/python-trace/tree/main/samples/snippets). - -## Method Calls - -> **WARNING**: Breaking change -Methods expect request objects. We provide a script that will convert most common use cases. - -* Install the library - -```py -python3 -m pip install google-cloud-trace -``` - -* The scripts `fixup_trace_v1_keywords.py` and `fixup_trace_v2_keywords.py` are shipped with the library. The script expects -an input directory (with the code to convert) and an empty destination directory. - -```sh -$ fixup_trace_v1_keywords.py --input-directory .samples/ --output-directory samples/ -``` - -**Before:** -```py -from google.cloud import trace_v1 - -client = trace_v1.TraceServiceClient() -project_id = "my-project" -response = client.list_traces(project_id) -``` - - -**After:** -```py -from google.cloud import trace_v1 - -client = trace_v1.TraceServiceClient() -project_id = "my-project" -response = client.list_traces(project_id=project_id) -``` - -### More Details - -In `google-cloud-trace<1.0.0`, parameters required by the API were positional parameters and optional parameters were keyword parameters. - -**Before:** -```py - def get_trace( - self, - project_id, - trace_id, - retry=google.api_core.gapic_v1.method.DEFAULT, - timeout=google.api_core.gapic_v1.method.DEFAULT, - metadata=None, - ): -``` - -In the 1.0.0 release, all methods have a single positional parameter `request`. Method docstrings indicate whether a parameter is required or optional. - -Some methods have additional keyword only parameters. The available parameters depend on the [`google.api.method_signature` annotation](https://github.com/googleapis/googleapis/blob/master/google/devtools/cloudtrace/v2/tracing.proto#L53) specified by the API producer. - - -**After:** -```py - def get_trace( - self, - request: trace.GetTraceRequest = None, - *, - project_id: str = None, - trace_id: str = None, - retry: retries.Retry = gapic_v1.method.DEFAULT, - timeout: float = None, - metadata: Sequence[Tuple[str, str]] = (), - ) -> trace.Trace: -``` - -> **NOTE:** The `request` parameter and flattened keyword parameters for the API are mutually exclusive. -> Passing both will result in an error. - - -Both of these calls are valid: - -```py -response = client.get_trace( - request={ - "project_id": project_id, - "trace_id", trace_id, - } -) -``` - -```py -response = client.get_trace( - project_id=project_id, - trace_id=trace_id, -) -``` - -This call is invalid because it mixes `request` with a keyword argument `trace_id`. Executing this code -will result in an error. - -```py -response = client.get_trace( - request={ - "project_id": project_id, - }, - trace_id=trace_id, -) -``` - - - -## Enums and Types - - -**WARNING**: Breaking change - -The submodules `types` is no longer available on the unversioned path `trace`. - -**Before:** -```py -from google.cloud import trace - -trace_ = trace.types.TraceSpan() -``` - - -**After:** -```py -from google.cloud - -trace_ = trace_v1.TraceSpan() -trace_ = trace_v1.types.TraceSpan() -``` diff --git a/packages/google-cloud-trace/docs/starting.html b/packages/google-cloud-trace/docs/starting.html deleted file mode 100644 index 9b81d6976cda..000000000000 --- a/packages/google-cloud-trace/docs/starting.html +++ /dev/null @@ -1,8 +0,0 @@ - - - - - - diff --git a/packages/google-cloud-videointelligence/scripts/fixup_keywords.py b/packages/google-cloud-videointelligence/scripts/fixup_keywords.py deleted file mode 100644 index cda96fc572ce..000000000000 --- a/packages/google-cloud-videointelligence/scripts/fixup_keywords.py +++ /dev/null @@ -1,179 +0,0 @@ -#! /usr/bin/env python3 -# -*- coding: utf-8 -*- - -# Copyright 2020 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. -# - -import argparse -import os -import libcst as cst -import pathlib -import sys -from typing import (Any, Callable, Dict, List, Sequence, Tuple) - - -def partition( - predicate: Callable[[Any], bool], - iterator: Sequence[Any] -) -> Tuple[List[Any], List[Any]]: - """A stable, out-of-place partition.""" - results = ([], []) - - for i in iterator: - results[int(predicate(i))].append(i) - - # Returns trueList, falseList - return results[1], results[0] - - -class videointelligenceCallTransformer(cst.CSTTransformer): - CTRL_PARAMS: Tuple[str] = ('retry', 'timeout', 'metadata') - METHOD_TO_PARAMS: Dict[str, Tuple[str]] = { - 'annotate_video': ('features', 'input_uri', 'input_content', 'video_context', 'output_uri', 'location_id', ), - - } - - def leave_Call(self, original: cst.Call, updated: cst.Call) -> cst.CSTNode: - try: - key = original.func.attr.value - kword_params = self.METHOD_TO_PARAMS[key] - except (AttributeError, KeyError): - # Either not a method from the API or too convoluted to be sure. - return updated - - # If the existing code is valid, keyword args come after positional args. - # Therefore, all positional args must map to the first parameters. - args, kwargs = partition(lambda a: not bool(a.keyword), updated.args) - if any(k.keyword.value == "request" for k in kwargs): - # We've already fixed this file, don't fix it again. - return updated - - kwargs, ctrl_kwargs = partition( - lambda a: not a.keyword.value in self.CTRL_PARAMS, - kwargs - ) - - args, ctrl_args = args[:len(kword_params)], args[len(kword_params):] - ctrl_kwargs.extend(cst.Arg(value=a.value, keyword=cst.Name(value=ctrl)) - for a, ctrl in zip(ctrl_args, self.CTRL_PARAMS)) - - request_arg = cst.Arg( - value=cst.Dict([ - cst.DictElement( - cst.SimpleString("'{}'".format(name)), - cst.Element(value=arg.value) - ) - # Note: the args + kwargs looks silly, but keep in mind that - # the control parameters had to be stripped out, and that - # those could have been passed positionally or by keyword. - for name, arg in zip(kword_params, args + kwargs)]), - keyword=cst.Name("request") - ) - - return updated.with_changes( - args=[request_arg] + ctrl_kwargs - ) - - -def fix_files( - in_dir: pathlib.Path, - out_dir: pathlib.Path, - *, - transformer=videointelligenceCallTransformer(), -): - """Duplicate the input dir to the output dir, fixing file method calls. - - Preconditions: - * in_dir is a real directory - * out_dir is a real, empty directory - """ - pyfile_gen = ( - pathlib.Path(os.path.join(root, f)) - for root, _, files in os.walk(in_dir) - for f in files if os.path.splitext(f)[1] == ".py" - ) - - for fpath in pyfile_gen: - with open(fpath, 'r') as f: - src = f.read() - - # Parse the code and insert method call fixes. - tree = cst.parse_module(src) - updated = tree.visit(transformer) - - # Create the path and directory structure for the new file. - updated_path = out_dir.joinpath(fpath.relative_to(in_dir)) - updated_path.parent.mkdir(parents=True, exist_ok=True) - - # Generate the updated source file at the corresponding path. - with open(updated_path, 'w') as f: - f.write(updated.code) - - -if __name__ == '__main__': - parser = argparse.ArgumentParser( - description="""Fix up source that uses the videointelligence client library. - -The existing sources are NOT overwritten but are copied to output_dir with changes made. - -Note: This tool operates at a best-effort level at converting positional - parameters in client method calls to keyword based parameters. - Cases where it WILL FAIL include - A) * or ** expansion in a method call. - B) Calls via function or method alias (includes free function calls) - C) Indirect or dispatched calls (e.g. the method is looked up dynamically) - - These all constitute false negatives. The tool will also detect false - positives when an API method shares a name with another method. -""") - parser.add_argument( - '-d', - '--input-directory', - required=True, - dest='input_dir', - help='the input directory to walk for python files to fix up', - ) - parser.add_argument( - '-o', - '--output-directory', - required=True, - dest='output_dir', - help='the directory to output files fixed via un-flattening', - ) - args = parser.parse_args() - input_dir = pathlib.Path(args.input_dir) - output_dir = pathlib.Path(args.output_dir) - if not input_dir.is_dir(): - print( - f"input directory '{input_dir}' does not exist or is not a directory", - file=sys.stderr, - ) - sys.exit(-1) - - if not output_dir.is_dir(): - print( - f"output directory '{output_dir}' does not exist or is not a directory", - file=sys.stderr, - ) - sys.exit(-1) - - if os.listdir(output_dir): - print( - f"output directory '{output_dir}' is not empty", - file=sys.stderr, - ) - sys.exit(-1) - - fix_files(input_dir, output_dir) diff --git a/packages/google-cloud-webrisk/UPGRADING.MD b/packages/google-cloud-webrisk/UPGRADING.MD deleted file mode 100644 index 4a211e08f0f3..000000000000 --- a/packages/google-cloud-webrisk/UPGRADING.MD +++ /dev/null @@ -1,122 +0,0 @@ -# 2.0.0 Migration Guide - -The 2.0 release of the `google-cloud-webrisk` client is a significant upgrade based on a [next-gen code generator](https://github.com/googleapis/gapic-generator-python), and includes substantial interface changes. Existing code written for earlier versions of this library will likely require updates to use this version. This document describes the changes that have been made, and what you need to do to update your usage. - -If you experience issues or have questions, please file an [issue](https://github.com/googleapis/python-webrisk/issues). - -## Supported Python Versions - -> **WARNING**: Breaking change - -The 2.0.0 release requires Python 3.6+. - - -## Method Calls - -> **WARNING**: Breaking change - -Methods expect request objects. We provide a script that will convert most common use cases. - -* Install the library and `libcst >= 0.2.5`. - -```py -python3 -m pip install google-cloud-webrisk libcst >= 0.2.5 -``` - -* The scripts `fixup_webrisk_v1_keywords.py` and `fixup_webrisk_v1beta1_keywords.py` shipped with the library. It expects -an input directory (with the code to convert) and an empty destination directory. - -```sh -$ fixup_webrisk_v1_keywords.py --input-directory .samples/ --output-directory samples/ -``` - -**Before:** -```py -from google.cloud import webrisk_v1 - -client = webrisk_v1.WebRiskServiceClient() -# TODO: Initialize `threat_types`: -threat_types = [] - -response = client.search_hashes(threat_types) -``` - - -**After:** -```py -from google.cloud import webrisk_v1 - -client = webrisk_v1.WebRiskServiceClient() - -response = client.search_hashes(request={"threat_types": "[]"}) - -``` - -### More Details - -In `google-cloud-webrisk<2.0.0`, parameters required by the API were positional parameters and optional parameters were keyword parameters. - -**Before:** -```py - def search_hashes( - self, - threat_types, - hash_prefix=None, - retry=google.api_core.gapic_v1.method.DEFAULT, - timeout=google.api_core.gapic_v1.method.DEFAULT, - metadata=None, - ): -``` - -In the 2.0.0 release, all methods have a single positional parameter `request`. Method docstrings indicate whether a parameter is required or optional. - -Some methods have additional keyword only parameters. The available parameters depend on the [`google.api.method_signature` annotation](https://github.com/googleapis/googleapis/blob/master/google/cloud/webrisk/v1/webrisk.proto#L74) specified by the API producer. - - -**After:** -```py - def search_hashes( - self, - request: webrisk.SearchHashesRequest = None, - *, - hash_prefix: bytes = None, - threat_types: Sequence[webrisk.ThreatType] = None, - retry: retries.Retry = gapic_v1.method.DEFAULT, - timeout: float = None, - metadata: Sequence[Tuple[str, str]] = (), - ) -> webrisk.SearchHashesResponse: -``` - -> **NOTE:** The `request` parameter and flattened keyword parameters for the API are mutually exclusive. -> Passing both will result in an error. - - -Both of these calls are valid: - -```py -response = client.search_hashes( - request={ - "hash_prefix": hash_prefix, - "threat_types": threat_types, - } -) -``` - -```py -response = client.search_hashes( - hash_prefix=hash_prefix, - threat_types=threat_types, -) -``` - -This call is invalid because it mixes `request` with a keyword argument `threat_types`. Executing this code -will result in an error. - -```py -response = client.synthesize_speech( - request={ - "hash_prefix": hash_prefix, - }, - threat_types=threat_types -) -``` diff --git a/scripts/client-post-processing/bigquery-storage-integration.yaml b/scripts/client-post-processing/bigquery-storage-integration.yaml index 3d42dc5822e0..9ae7cf942bc0 100644 --- a/scripts/client-post-processing/bigquery-storage-integration.yaml +++ b/scripts/client-post-processing/bigquery-storage-integration.yaml @@ -508,11 +508,5 @@ replacements: bigquery_storage_v1beta2/types_ bigquery_storage_v1alpha/services_ bigquery_storage_v1alpha/types_\n\n - Migration Guide - ---------------\n - See the guide below for instructions on migrating to the 2.x release of this library.\n - .. toctree:: - :maxdepth: 2\n - UPGRADING\n Changelog count: 1