|
| 1 | +# 3.0.0 Migration Guide |
| 2 | + |
| 3 | +This document describes the breaking changes that have been made, and what you need to do to update your usage. |
| 4 | + |
| 5 | +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. |
| 6 | + |
| 7 | +If you experience issues or have questions, please file an [issue](https://github.com/googleapis/python-datacatalog/issues). |
| 8 | + |
| 9 | +## Supported Python Versions |
| 10 | + |
| 11 | +> **WARNING**: Breaking change |
| 12 | +> |
| 13 | +> The 2.0.0 release requires Python 3.6+. |
| 14 | +
|
| 15 | + |
| 16 | +## Method Calls |
| 17 | + |
| 18 | +> **WARNING**: Breaking change |
| 19 | +> |
| 20 | +> Methods expect request objects. We provide a script that will convert most common use cases. |
| 21 | +
|
| 22 | +* Install the library |
| 23 | + |
| 24 | +```py |
| 25 | +python3 -m pip install google-cloud-datacatalog |
| 26 | +``` |
| 27 | + |
| 28 | +* The script `fixup_datacatalog_v1_keywords.py` is shipped with the library. It expects |
| 29 | +an input directory (with the code to convert) and an empty destination directory. |
| 30 | + |
| 31 | +```sh |
| 32 | +$ fixup_datacatalog_v1_keywords.py --input-directory .samples/ --output-directory samples/ |
| 33 | +``` |
| 34 | + |
| 35 | +**Before:** |
| 36 | +```py |
| 37 | +from google.cloud import datacatalog_v1 |
| 38 | +datacatalog = datacatalog_v1.DataCatalogClient() |
| 39 | +return datacatalog.lookup_entry(linked_resource=resource_name) |
| 40 | +``` |
| 41 | + |
| 42 | + |
| 43 | +**After:** |
| 44 | +```py |
| 45 | +from google.cloud import datacatalog_v1 |
| 46 | +datacatalog = datacatalog_v1.DataCatalogClient() |
| 47 | +return datacatalog.lookup_entry(request={'linked_resource': resource_name}) |
| 48 | +``` |
| 49 | + |
| 50 | +### More Details |
| 51 | + |
| 52 | +In `google-cloud-datacatalog<=1.0.0`, parameters required by the API were positional parameters and optional parameters were keyword parameters. |
| 53 | + |
| 54 | +**Before:** |
| 55 | +```py |
| 56 | + def create_entry_group( |
| 57 | + self, |
| 58 | + parent, |
| 59 | + entry_group_id, |
| 60 | + entry_group=None, |
| 61 | + retry=google.api_core.gapic_v1.method.DEFAULT, |
| 62 | + timeout=google.api_core.gapic_v1.method.DEFAULT, |
| 63 | + metadata=None, |
| 64 | + ): |
| 65 | +``` |
| 66 | + |
| 67 | +Since the 2.0.0 release, all methods have a single positional parameter `request`. Method docstrings indicate whether a parameter is required or optional. |
| 68 | + |
| 69 | +Some methods have additional keyword only parameters. The available parameters depend on the `google.api.method_signature` annotation specified by the API producer. |
| 70 | + |
| 71 | + |
| 72 | +**After:** |
| 73 | +```py |
| 74 | + def create_entry_group( |
| 75 | + self, |
| 76 | + request: datacatalog.CreateEntryGroupRequest = None, |
| 77 | + *, |
| 78 | + parent: str = None, |
| 79 | + entry_group_id: str = None, |
| 80 | + entry_group: datacatalog.EntryGroup = None, |
| 81 | + retry: retries.Retry = gapic_v1.method.DEFAULT, |
| 82 | + timeout: float = None, |
| 83 | + metadata: Sequence[Tuple[str, str]] = (), |
| 84 | + ) -> datacatalog.EntryGroup: |
| 85 | +``` |
| 86 | + |
| 87 | +> **NOTE:** The `request` parameter and flattened keyword parameters for the API are mutually exclusive. |
| 88 | +> Passing both will result in an error. |
| 89 | +
|
| 90 | +Both of these calls are valid: |
| 91 | + |
| 92 | +```py |
| 93 | +response = client.create_entry_group( |
| 94 | + request={ |
| 95 | + "parent": parent, |
| 96 | + "entry_group_id": entry_group_id, |
| 97 | + "entry_group": entry_group |
| 98 | + } |
| 99 | +) |
| 100 | +``` |
| 101 | + |
| 102 | +```py |
| 103 | +response = client.create_entry_group( |
| 104 | + parent=parent, |
| 105 | + entry_group_id=entry_group_id, |
| 106 | + entry_group=entry_group |
| 107 | +) # Make an API request. |
| 108 | +``` |
| 109 | + |
| 110 | +This call is invalid because it mixes `request` with a keyword argument `entry_group`. Executing this code |
| 111 | +will result in an error. |
| 112 | + |
| 113 | +```py |
| 114 | +response = client.create_entry_group( |
| 115 | + request={ |
| 116 | + "parent": parent, |
| 117 | + "entry_group_id"=entry_group_id |
| 118 | + }, |
| 119 | + entry_group=entry_group |
| 120 | +) |
| 121 | +``` |
| 122 | + |
| 123 | + |
| 124 | + |
| 125 | +## Enums and Types |
| 126 | + |
| 127 | +> **WARNING**: Breaking changes |
| 128 | +> |
| 129 | +> The submodules `enums` and `types` have been removed; the `type` attributes were renamed to `type_` to avoid name collisions. |
| 130 | +
|
| 131 | +**Before:** |
| 132 | +```py |
| 133 | +from google.cloud import datacatalog_v1 |
| 134 | +entry = datacatalog_v1.types.Entry() |
| 135 | +entry.type = datacatalog_v1.enums.EntryType.FILESET |
| 136 | +``` |
| 137 | + |
| 138 | + |
| 139 | +**After:** |
| 140 | +```py |
| 141 | +from google.cloud import datacatalog_v1 |
| 142 | +entry = datacatalog_v1.Entry() |
| 143 | +entry.type_ = datacatalog_v1.EntryType.FILESET |
| 144 | +``` |
| 145 | + |
| 146 | +The renamed attributes are: |
| 147 | + |
| 148 | +* `TagTemplateField.type` -> `TagTemplatedField.type_` |
| 149 | +* `ColumnSchema.type` -> `ColumnSchema.type_` |
| 150 | +* `Entry.type` -> `Entry.type_` |
| 151 | + |
| 152 | +## Common Resource Path Helper Methods |
| 153 | + |
| 154 | +The `location_path` method existing in `google-cloud-datacatalog<=1.0.0` was renamed to `common_location_path` in v3.0.0. |
| 155 | + |
| 156 | +If you are upgrading from v1.0.0 or lower, modify your code to use new method name. |
| 157 | + |
| 158 | +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. |
| 159 | + |
| 160 | +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 commit comments