From 571171e65fad5939ce3f20ec63ac35c8c80f2e2a Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Wed, 1 Dec 2021 15:33:58 -0600 Subject: [PATCH] docs: convert UPGRADING guide to RST to fix table formatting (#268) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: convert UPGRADING guide to RST to fix table formatting * use latest post processor image * 🦉 Updates from OwlBot See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md Co-authored-by: Owl Bot Co-authored-by: Anthonios Partheniou --- .github/.OwlBot.lock.yaml | 2 +- CHANGELOG.md | 2 +- UPGRADING.md | 176 --------------------------------- UPGRADING.rst | 201 ++++++++++++++++++++++++++++++++++++++ docs/UPGRADING.md | 1 - docs/UPGRADING.rst | 1 + 6 files changed, 204 insertions(+), 179 deletions(-) delete mode 100644 UPGRADING.md create mode 100644 UPGRADING.rst delete mode 120000 docs/UPGRADING.md create mode 120000 docs/UPGRADING.rst diff --git a/.github/.OwlBot.lock.yaml b/.github/.OwlBot.lock.yaml index 7519fa3a..a67698f8 100644 --- a/.github/.OwlBot.lock.yaml +++ b/.github/.OwlBot.lock.yaml @@ -1,3 +1,3 @@ docker: image: gcr.io/cloud-devrel-public-resources/owlbot-python:latest - digest: sha256:0e18b9475fbeb12d9ad4302283171edebb6baf2dfca1bd215ee3b34ed79d95d7 + digest: sha256:74124fe59b8859f30143dcdea7b78300046d97de816dc53c0e381308a5f4f8bc diff --git a/CHANGELOG.md b/CHANGELOG.md index 03450f7a..b0fcf447 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -196,7 +196,7 @@ ### ⚠ BREAKING CHANGES -* This release has breaking changes. See the [2.0.0 Migration Guide](https://github.com/googleapis/python-datacatalog/blob/main/UPGRADING.md) for details. +* This release has breaking changes. See the [2.0.0 Migration Guide](https://github.com/googleapis/python-datacatalog/blob/main/UPGRADING.rst) for details. ### Features diff --git a/UPGRADING.md b/UPGRADING.md deleted file mode 100644 index 09aaf383..00000000 --- a/UPGRADING.md +++ /dev/null @@ -1,176 +0,0 @@ -# 3.0.0 Migration Guide - -This document describes the breaking changes that have been made, and what you need to do to update your usage. - -The most significant change was introduced at v2.0 release based on a [next-gen code generator](https://github.com/googleapis/gapic-generator-python), and includes substantial interface changes. Existing code written for eariler versions of this library will likely require updates to use this version. - -If you experience issues or have questions, please file an [issue](https://github.com/googleapis/python-datacatalog/issues). - -## Supported Python Versions - -| Applicable previous versions | -|------------------------------| -| v1.0.0 or lower | - -> **WARNING**: Breaking change -> -> The 2.0.0 release requires Python 3.6+. - - -## Method Calls - -| Applicable previous versions | -|------------------------------| -| v1.0.0 or lower | - -> **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-datacatalog -``` - -* The script `fixup_datacatalog_v1_keywords.py` is shipped with the library. It expects -an input directory (with the code to convert) and an empty destination directory. - -```sh -$ fixup_datacatalog_v1_keywords.py --input-directory .samples/ --output-directory samples/ -``` - -**Before:** -```py -from google.cloud import datacatalog_v1 -datacatalog = datacatalog_v1.DataCatalogClient() -return datacatalog.lookup_entry(linked_resource=resource_name) -``` - - -**After:** -```py -from google.cloud import datacatalog_v1 -datacatalog = datacatalog_v1.DataCatalogClient() -return datacatalog.lookup_entry(request={'linked_resource': resource_name}) -``` - -### More Details - -In `google-cloud-datacatalog<=1.0.0`, parameters required by the API were positional parameters and optional parameters were keyword parameters. - -**Before:** -```py - def create_entry_group( - self, - parent, - entry_group_id, - entry_group=None, - retry=google.api_core.gapic_v1.method.DEFAULT, - timeout=google.api_core.gapic_v1.method.DEFAULT, - metadata=None, - ): -``` - -Since 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 specified by the API producer. - - -**After:** -```py - def create_entry_group( - self, - request: datacatalog.CreateEntryGroupRequest = None, - *, - parent: str = None, - entry_group_id: str = None, - entry_group: datacatalog.EntryGroup = None, - retry: retries.Retry = gapic_v1.method.DEFAULT, - timeout: float = None, - metadata: Sequence[Tuple[str, str]] = (), - ) -> datacatalog.EntryGroup: -``` - -> **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_entry_group( - request={ - "parent": parent, - "entry_group_id": entry_group_id, - "entry_group": entry_group - } -) -``` - -```py -response = client.create_entry_group( - parent=parent, - entry_group_id=entry_group_id, - entry_group=entry_group -) # Make an API request. -``` - -This call is invalid because it mixes `request` with a keyword argument `entry_group`. Executing this code -will result in an error. - -```py -response = client.create_entry_group( - request={ - "parent": parent, - "entry_group_id"=entry_group_id - }, - entry_group=entry_group -) -``` - - - -## Enums and Types - -| Applicable previous versions | -|:-----------------------------| -| v2.0.0 or lower | - -> **WARNING**: Breaking changes -> -> The submodules `enums` and `types` have been removed; the `type` attributes were renamed to `type_` to avoid name collisions. - -**Before:** -```py -from google.cloud import datacatalog_v1 -entry = datacatalog_v1.types.Entry() -entry.type = datacatalog_v1.enums.EntryType.FILESET -``` - - -**After:** -```py -from google.cloud import datacatalog_v1 -entry = datacatalog_v1.Entry() -entry.type_ = datacatalog_v1.EntryType.FILESET -``` - -The renamed attributes are: - -* `TagTemplateField.type` -> `TagTemplatedField.type_` -* `ColumnSchema.type` -> `ColumnSchema.type_` -* `Entry.type` -> `Entry.type_` - -## Common Resource Path Helper Methods - -| Applicable previous versions | -|:-----------------------------| -| v1.0.0 or lower | - -The `location_path` method existing in `google-cloud-datacatalog<=1.0.0` was renamed to `common_location_path` in v3.0.0. - -If you are upgrading from v1.0.0 or lower, modify your code to use new method name. - -If you are upgrading from v2.0.0, and constructing paths manually as described in [previous upgrade guide](https://github.com/googleapis/python-datacatalog/blob/v2.0.0/UPGRADING.md#project-path-helper-methods), now you can use `common_location_path` method. - -There are also more resource path helper methods were added: `common_billing_account_path`, `common_folder_path`, `common_organization_path`, and `common_project_path`. diff --git a/UPGRADING.rst b/UPGRADING.rst new file mode 100644 index 00000000..17e35edb --- /dev/null +++ b/UPGRADING.rst @@ -0,0 +1,201 @@ +3.0.0 Migration Guide +===================== + +This document describes the breaking changes that have been made, and what you need to do to update your usage. + +The most significant change was introduced at v2.0 release based on a `next-gen code generator `_, and includes substantial interface changes. Existing code written for eariler versions of this library will likely require updates to use this version. + +If you experience issues or have questions, please file an `issue `_. + +Supported Python Versions +------------------------- + ++------------------------------+ +| Applicable previous versions | ++==============================+ +| v1.0.0 or lower | ++------------------------------+ + +.. warning: + + **Breaking change:** + The 2.0.0 release requires Python 3.6+. + + +Method Calls +------------ + ++------------------------------+ +| Applicable previous versions | ++==============================+ +| v1.0.0 or lower | ++------------------------------+ + +.. warning: + + **Breaking change:** + Methods expect request objects. We provide a script that will convert most common use cases. + +* Install the library + +.. code-block:: shell + + python3 -m pip install google-cloud-datacatalog + +* The script `fixup_datacatalog_v1_keywords.py` is shipped with the library. It expects + an input directory (with the code to convert) and an empty destination directory. + +.. code-block:: shell + + fixup_datacatalog_v1_keywords.py --input-directory .samples/ --output-directory samples/ + +**Before:** + +.. code-block:: python + + from google.cloud import datacatalog_v1 + datacatalog = datacatalog_v1.DataCatalogClient() + return datacatalog.lookup_entry(linked_resource=resource_name) + + +**After:** + +.. code-block:: python + + from google.cloud import datacatalog_v1 + datacatalog = datacatalog_v1.DataCatalogClient() + return datacatalog.lookup_entry(request={'linked_resource': resource_name}) + +More Details +^^^^^^^^^^^^ + +In `google-cloud-datacatalog<=1.0.0`, parameters required by the API were positional parameters and optional parameters were keyword parameters. + +**Before:** + +.. code-block:: python + + def create_entry_group( + self, + parent, + entry_group_id, + entry_group=None, + retry=google.api_core.gapic_v1.method.DEFAULT, + timeout=google.api_core.gapic_v1.method.DEFAULT, + metadata=None, + ): + +Since 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 specified by the API producer. + + +**After:** + +.. code-block:: python + + def create_entry_group( + self, + request: datacatalog.CreateEntryGroupRequest = None, + *, + parent: str = None, + entry_group_id: str = None, + entry_group: datacatalog.EntryGroup = None, + retry: retries.Retry = gapic_v1.method.DEFAULT, + timeout: float = None, + metadata: Sequence[Tuple[str, str]] = (), + ) -> datacatalog.EntryGroup: + +.. 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: + +.. code-block:: python + + response = client.create_entry_group( + request={ + "parent": parent, + "entry_group_id": entry_group_id, + "entry_group": entry_group + } + ) + +.. code-block:: python + + response = client.create_entry_group( + parent=parent, + entry_group_id=entry_group_id, + entry_group=entry_group + ) # Make an API request. + +This call is invalid because it mixes `request` with a keyword argument `entry_group`. Executing this code +will result in an error. + +.. code-block:: python + + response = client.create_entry_group( + request={ + "parent": parent, + "entry_group_id"=entry_group_id + }, + entry_group=entry_group + ) + + + +Enums and Types +--------------- + ++------------------------------+ +| Applicable previous versions | ++==============================+ +| v2.0.0 or lower | ++------------------------------+ + +.. warning: + + **Breaking changes:** + The submodules `enums` and `types` have been removed; the `type` attributes were renamed to `type_` to avoid name collisions. + +**Before:** + +.. code-block:: python + + from google.cloud import datacatalog_v1 + entry = datacatalog_v1.types.Entry() + entry.type = datacatalog_v1.enums.EntryType.FILESET + + +**After:** + +.. code-block:: python + + from google.cloud import datacatalog_v1 + entry = datacatalog_v1.Entry() + entry.type_ = datacatalog_v1.EntryType.FILESET + +The renamed attributes are: + +* `TagTemplateField.type` -> `TagTemplatedField.type_` +* `ColumnSchema.type` -> `ColumnSchema.type_` +* `Entry.type` -> `Entry.type_` + +Common Resource Path Helper Methods +----------------------------------- + ++------------------------------+ +| Applicable previous versions | ++==============================+ +| v1.0.0 or lower | ++------------------------------+ + +The `location_path` method existing in `google-cloud-datacatalog<=1.0.0` was renamed to `common_location_path` in v3.0.0. + +If you are upgrading from v1.0.0 or lower, modify your code to use new method name. + +If you are upgrading from v2.0.0, and constructing paths manually as described in `previous upgrade guide `_, now you can use `common_location_path` method. + +There are also more resource path helper methods were added: `common_billing_account_path`, `common_folder_path`, `common_organization_path`, and `common_project_path`. diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md deleted file mode 120000 index 01097c8c..00000000 --- a/docs/UPGRADING.md +++ /dev/null @@ -1 +0,0 @@ -../UPGRADING.md \ No newline at end of file diff --git a/docs/UPGRADING.rst b/docs/UPGRADING.rst new file mode 120000 index 00000000..d557d0e8 --- /dev/null +++ b/docs/UPGRADING.rst @@ -0,0 +1 @@ +../UPGRADING.rst \ No newline at end of file