Skip to content
This repository has been archived by the owner on Sep 5, 2023. It is now read-only.

Commit

Permalink
docs: fix upgrade guide (#114)
Browse files Browse the repository at this point in the history
Current upgrade guide is confusing especially when upgrading from v2.0.0 to v3.0.0 because some of the change is only introduced at v2.0.0. I fixed this.

This is just a documentation fix rather than code fix, so note that following checks are not passed

---

Thank you for opening a Pull Request! Before submitting your PR, there are a few things you can do to make sure it goes smoothly:
- [ ] Make sure to open an issue as a [bug/issue](https://github.com/googleapis/python-datacatalog/issues/new/choose) before writing your code!  That way we can discuss the change, evaluate designs, and agree on the general idea
- [ ] Ensure the tests and linter pass
- [ ] Code coverage does not decrease (if any source code was changed)
- [ ] Appropriate docs were updated (if necessary)

Fixes #<issue_number_goes_here> 🦕

---

## Additional question

There are three way to invoke API-calling methods: (1) pass keyword arguments, (2) pass `request` argument with request class and (3) pass `request` argument with dict.

The auto-migration tool `fixup_datacatalog_v1_keywords.py` fixes code to use method (3) even if the methods accepts keyword arguments. However, IMO, it's poorly typed and not linter/autocompletion-friendly.

Actually what is the recommended way? And is there a plan to remove support of method (1)?

| | Available since | Typed | Note |
|:---|:---|:---|:---|
| (1) | v1 | ◎ (since v2) | |
| (2) | v2 | △ | Code looks redundant |
| (3) | v2 | ☓ | |

(1)

```py
response = client.create_entry_group(
    parent=parent, 
    entry_group_id=entry_group_id,
    entry_group=entry_group
)
```

(2)

```py
response = client.create_entry_group(
    datacatalog.CreateEntryGroupRequest(
        parent=parent, 
        entry_group_id=entry_group_id,
        entry_group=entry_group
    )
)
```

(3)

```py
response = client.create_entry_group(
    request={
        "parent": parent,
        "entry_group_id": entry_group_id,
        "entry_group": entry_group
    }
)
```
  • Loading branch information
tmshn committed Feb 19, 2021
1 parent 2f98f22 commit 4bfa587
Showing 1 changed file with 33 additions and 5 deletions.
38 changes: 33 additions & 5 deletions UPGRADING.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,28 @@
# 3.0.0 Migration Guide

The 3.0 release of the `google-cloud-datacatalog` 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.
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 3.0.0 release requires Python 3.6+.
> 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.
Expand Down Expand Up @@ -62,7 +72,7 @@ In `google-cloud-datacatalog<=1.0.0`, parameters required by the API were positi
):
```

In the 3.0.0 release, all methods have a single positional parameter `request`. Method docstrings indicate whether a parameter is required or optional.
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.

Expand Down Expand Up @@ -122,6 +132,9 @@ response = client.create_entry_group(

## Enums and Types

| Applicable previous versions |
|:-----------------------------|
| v2.0.0 or lower |

> **WARNING**: Breaking changes
>
Expand All @@ -142,7 +155,22 @@ 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

The `location_path` method existing in `google-cloud-datacatalog<=1.0.0` was renamed to `common_location_path`.
And more resource path helper methods were added: `common_billing_account_path`, `common_folder_path`, `common_organization_path`, and `common_project_path`.
| 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`.

0 comments on commit 4bfa587

Please sign in to comment.