feat: add a static copy of legacy proto-based types (#1000)

* feat: add a static copy of legacy proto SQL types

* Exclude legacy types from docs generation

* Exclude legacy types from type checks

* Exclude legacy types from test coverage

* Emit warning if importing legacy types

* Re-introduce proto-related dependencies

* Expose legacy types in reference docs

Author: plamut

.coveragerc

@@ -6,6 +6,7 @@ fail_under = 100
 show_missing = True
 omit =
     google/cloud/bigquery/__init__.py
+    google/cloud/bigquery_v2/*  # Legacy proto-based types.
 exclude_lines =
     # Re-enable the standard pragma
     pragma: NO COVER

UPGRADING.md

@@ -11,6 +11,10 @@ See the License for the specific language governing permissions and
 limitations under the License.
 -->
 
+# 3.0.0 Migration Guide
+
+TODO
+
 
 # 2.0.0 Migration Guide
 
@@ -56,4 +60,4 @@ distance_type = enums.Model.DistanceType.COSINE
 from google.cloud.bigquery_v2 import types
 
 distance_type = types.Model.DistanceType.COSINE
-```
+```

docs/bigquery/legacy_proto_types.rst

@@ -0,0 +1,14 @@
+Legacy proto-based Types for Google Cloud Bigquery v2 API
+=========================================================
+
+.. warning::
+    These types are provided for backward compatibility only, and are not maintained
+    anymore. They might also differ from the types uspported on the backend. It is
+    therefore strongly advised to migrate to the types found in :doc:`standard_sql`.
+
+    Also see the :doc:`3.0.0 Migration Guide<../UPGRADING>` for more information.
+
+.. automodule:: google.cloud.bigquery_v2.types
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/conf.py

@@ -109,6 +109,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 exclude_patterns = [
+    "google/cloud/bigquery_v2/**",  # Legacy proto-based types.
     "_build",
     "**/.nox/**/*",
     "samples/AUTHORING_GUIDE.md",
@@ -365,6 +366,8 @@
     "grpc": ("https://grpc.github.io/grpc/python/", None),
     "pandas": ("http://pandas.pydata.org/pandas-docs/stable/", None),
     "geopandas": ("https://geopandas.org/", None),
+    "proto-plus": ("https://proto-plus-python.readthedocs.io/en/latest/", None),
+    "protobuf": ("https://googleapis.dev/python/protobuf/latest/", None),
 }
 
 

docs/reference.rst

@@ -204,3 +204,18 @@ Helper SQL type classes.
     :maxdepth: 2
 
     bigquery/standard_sql
+
+
+Legacy proto-based Types (deprecated)
+=====================================
+
+The legacy type classes based on protocol buffers.
+
+.. deprecated:: 3.0.0
+    These types are provided for backward compatibility only, and are not maintained
+    anymore.
+
+.. toctree::
+    :maxdepth: 2
+
+    bigquery/legacy_proto_types

google/cloud/bigquery_v2/__init__.py

@@ -0,0 +1,56 @@
+# -*- 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 warnings
+
+from .types.encryption_config import EncryptionConfiguration
+from .types.model import DeleteModelRequest
+from .types.model import GetModelRequest
+from .types.model import ListModelsRequest
+from .types.model import ListModelsResponse
+from .types.model import Model
+from .types.model import PatchModelRequest
+from .types.model_reference import ModelReference
+from .types.standard_sql import StandardSqlDataType
+from .types.standard_sql import StandardSqlField
+from .types.standard_sql import StandardSqlStructType
+from .types.standard_sql import StandardSqlTableType
+from .types.table_reference import TableReference
+
+
+_LEGACY_MSG = (
+    "Legacy proto-based types from bigquery_v2 are not maintained anymore, "
+    "use types defined in google.cloud.bigquery instead."
+)
+
+warnings.warn(_LEGACY_MSG, category=DeprecationWarning)
+
+
+__all__ = (
+    "DeleteModelRequest",
+    "EncryptionConfiguration",
+    "GetModelRequest",
+    "ListModelsRequest",
+    "ListModelsResponse",
+    "Model",
+    "ModelReference",
+    "PatchModelRequest",
+    "StandardSqlDataType",
+    "StandardSqlField",
+    "StandardSqlStructType",
+    "StandardSqlTableType",
+    "TableReference",
+)

google/cloud/bigquery_v2/types/__init__.py

@@ -0,0 +1,48 @@
+# -*- 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.
+#
+from .encryption_config import EncryptionConfiguration
+from .model import (
+    DeleteModelRequest,
+    GetModelRequest,
+    ListModelsRequest,
+    ListModelsResponse,
+    Model,
+    PatchModelRequest,
+)
+from .model_reference import ModelReference
+from .standard_sql import (
+    StandardSqlDataType,
+    StandardSqlField,
+    StandardSqlStructType,
+    StandardSqlTableType,
+)
+from .table_reference import TableReference
+
+__all__ = (
+    "EncryptionConfiguration",
+    "DeleteModelRequest",
+    "GetModelRequest",
+    "ListModelsRequest",
+    "ListModelsResponse",
+    "Model",
+    "PatchModelRequest",
+    "ModelReference",
+    "StandardSqlDataType",
+    "StandardSqlField",
+    "StandardSqlStructType",
+    "StandardSqlTableType",
+    "TableReference",
+)

google/cloud/bigquery_v2/types/encryption_config.py

@@ -0,0 +1,42 @@
+# -*- 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 proto  # type: ignore
+
+from google.protobuf import wrappers_pb2  # type: ignore
+
+
+__protobuf__ = proto.module(
+    package="google.cloud.bigquery.v2", manifest={"EncryptionConfiguration",},
+)
+
+
+class EncryptionConfiguration(proto.Message):
+    r"""
+    Attributes:
+        kms_key_name (google.protobuf.wrappers_pb2.StringValue):
+            Optional. Describes the Cloud KMS encryption
+            key that will be used to protect destination
+            BigQuery table. The BigQuery Service Account
+            associated with your project requires access to
+            this encryption key.
+    """
+
+    kms_key_name = proto.Field(
+        proto.MESSAGE, number=1, message=wrappers_pb2.StringValue,
+    )
+
+
+__all__ = tuple(sorted(__protobuf__.manifest))