From 5924bdc9c51f3d34f7fa6f350d871688601ecad6 Mon Sep 17 00:00:00 2001 From: "gcf-owl-bot[bot]" <78513119+gcf-owl-bot[bot]@users.noreply.github.com> Date: Fri, 20 Jan 2023 12:55:23 -0500 Subject: [PATCH 1/2] docs: Add documentation for enums (#679) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: Add documentation for enums fix: Add context manager return types chore: Update gapic-generator-python to v1.8.1 PiperOrigin-RevId: 503210727 Source-Link: https://github.com/googleapis/googleapis/commit/a391fd1dac18dfdfa00c18c8404f2c3a6ff8e98e Source-Link: https://github.com/googleapis/googleapis-gen/commit/0080f830dec37c3384157082bce279e37079ea58 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiMDA4MGY4MzBkZWMzN2MzMzg0MTU3MDgyYmNlMjc5ZTM3MDc5ZWE1OCJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md Co-authored-by: Owl Bot --- .../services/firestore_admin/client.py | 2 +- .../firestore_admin_v1/types/database.py | 49 ++++++- .../cloud/firestore_admin_v1/types/field.py | 23 +++- .../cloud/firestore_admin_v1/types/index.py | 65 +++++++++- .../firestore_admin_v1/types/operation.py | 50 ++++++- google/cloud/firestore_bundle/types/bundle.py | 6 + .../firestore_v1/services/firestore/client.py | 2 +- google/cloud/firestore_v1/types/firestore.py | 29 ++++- google/cloud/firestore_v1/types/query.py | 122 +++++++++++++++++- google/cloud/firestore_v1/types/write.py | 13 +- 10 files changed, 345 insertions(+), 16 deletions(-) diff --git a/google/cloud/firestore_admin_v1/services/firestore_admin/client.py b/google/cloud/firestore_admin_v1/services/firestore_admin/client.py index d950ecdaa5..0e38499953 100644 --- a/google/cloud/firestore_admin_v1/services/firestore_admin/client.py +++ b/google/cloud/firestore_admin_v1/services/firestore_admin/client.py @@ -1945,7 +1945,7 @@ def sample_update_database(): # Done; return the response. return response - def __enter__(self): + def __enter__(self) -> "FirestoreAdminClient": return self def __exit__(self, type, value, traceback): diff --git a/google/cloud/firestore_admin_v1/types/database.py b/google/cloud/firestore_admin_v1/types/database.py index 953bac60d6..31f80880a6 100644 --- a/google/cloud/firestore_admin_v1/types/database.py +++ b/google/cloud/firestore_admin_v1/types/database.py @@ -74,20 +74,65 @@ class DatabaseType(proto.Enum): for information about how to choose. Mode changes are only allowed if the database is empty. + + Values: + DATABASE_TYPE_UNSPECIFIED (0): + The default value. This value is used if the + database type is omitted. + FIRESTORE_NATIVE (1): + Firestore Native Mode + DATASTORE_MODE (2): + Firestore in Datastore Mode. """ DATABASE_TYPE_UNSPECIFIED = 0 FIRESTORE_NATIVE = 1 DATASTORE_MODE = 2 class ConcurrencyMode(proto.Enum): - r"""The type of concurrency control mode for transactions.""" + r"""The type of concurrency control mode for transactions. + + Values: + CONCURRENCY_MODE_UNSPECIFIED (0): + Not used. + OPTIMISTIC (1): + Use optimistic concurrency control by + default. This mode is available for Cloud + Firestore databases. + PESSIMISTIC (2): + Use pessimistic concurrency control by + default. This mode is available for Cloud + Firestore databases. + This is the default setting for Cloud Firestore. + OPTIMISTIC_WITH_ENTITY_GROUPS (3): + Use optimistic concurrency control with + entity groups by default. + This is the only available mode for Cloud + Datastore. + This mode is also available for Cloud Firestore + with Datastore Mode but is not recommended. + """ CONCURRENCY_MODE_UNSPECIFIED = 0 OPTIMISTIC = 1 PESSIMISTIC = 2 OPTIMISTIC_WITH_ENTITY_GROUPS = 3 class AppEngineIntegrationMode(proto.Enum): - r"""The type of App Engine integration mode.""" + r"""The type of App Engine integration mode. + + Values: + APP_ENGINE_INTEGRATION_MODE_UNSPECIFIED (0): + Not used. + ENABLED (1): + If an App Engine application exists in the + same region as this database, App Engine + configuration will impact this database. This + includes disabling of the application & + database, as well as disabling writes to the + database. + DISABLED (2): + Appengine has no affect on the ability of + this database to serve requests. + """ APP_ENGINE_INTEGRATION_MODE_UNSPECIFIED = 0 ENABLED = 1 DISABLED = 2 diff --git a/google/cloud/firestore_admin_v1/types/field.py b/google/cloud/firestore_admin_v1/types/field.py index 5e722a12cb..bb21b6121a 100644 --- a/google/cloud/firestore_admin_v1/types/field.py +++ b/google/cloud/firestore_admin_v1/types/field.py @@ -129,7 +129,28 @@ class TtlConfig(proto.Message): """ class State(proto.Enum): - r"""The state of applying the TTL configuration to all documents.""" + r"""The state of applying the TTL configuration to all documents. + + Values: + STATE_UNSPECIFIED (0): + The state is unspecified or unknown. + CREATING (1): + The TTL is being applied. There is an active + long-running operation to track the change. + Newly written documents will have TTLs applied + as requested. Requested TTLs on existing + documents are still being processed. When TTLs + on all existing documents have been processed, + the state will move to 'ACTIVE'. + ACTIVE (2): + The TTL is active for all documents. + NEEDS_REPAIR (3): + The TTL configuration could not be enabled for all existing + documents. Newly written documents will continue to have + their TTL applied. The LRO returned when last attempting to + enable TTL for this ``Field`` has failed, and may have more + details. + """ STATE_UNSPECIFIED = 0 CREATING = 1 ACTIVE = 2 diff --git a/google/cloud/firestore_admin_v1/types/index.py b/google/cloud/firestore_admin_v1/types/index.py index 72ac243f3d..f3897dfb90 100644 --- a/google/cloud/firestore_admin_v1/types/index.py +++ b/google/cloud/firestore_admin_v1/types/index.py @@ -69,6 +69,22 @@ class Index(proto.Message): class QueryScope(proto.Enum): r"""Query Scope defines the scope at which a query is run. This is specified on a StructuredQuery's ``from`` field. + + Values: + QUERY_SCOPE_UNSPECIFIED (0): + The query scope is unspecified. Not a valid + option. + COLLECTION (1): + Indexes with a collection query scope + specified allow queries against a collection + that is the child of a specific document, + specified at query time, and that has the + collection id specified by the index. + COLLECTION_GROUP (2): + Indexes with a collection group query scope + specified allow queries against all collections + that has the collection id specified by the + index. """ QUERY_SCOPE_UNSPECIFIED = 0 COLLECTION = 1 @@ -80,6 +96,31 @@ class State(proto.Enum): will transition to the ``READY`` state. If the index creation encounters a problem, the index will transition to the ``NEEDS_REPAIR`` state. + + Values: + STATE_UNSPECIFIED (0): + The state is unspecified. + CREATING (1): + The index is being created. + There is an active long-running operation for + the index. The index is updated when writing a + document. Some index data may exist. + READY (2): + The index is ready to be used. + The index is updated when writing a document. + The index is fully populated from all stored + documents it applies to. + NEEDS_REPAIR (3): + The index was being created, but something + went wrong. There is no active long-running + operation for the index, and the most recently + finished long-running operation failed. The + index is not updated when writing a document. + Some index data may exist. + Use the google.longrunning.Operations API to + determine why the operation that last attempted + to create this index failed, then re-create the + index. """ STATE_UNSPECIFIED = 0 CREATING = 1 @@ -115,13 +156,33 @@ class IndexField(proto.Message): """ class Order(proto.Enum): - r"""The supported orderings.""" + r"""The supported orderings. + + Values: + ORDER_UNSPECIFIED (0): + The ordering is unspecified. Not a valid + option. + ASCENDING (1): + The field is ordered by ascending field + value. + DESCENDING (2): + The field is ordered by descending field + value. + """ ORDER_UNSPECIFIED = 0 ASCENDING = 1 DESCENDING = 2 class ArrayConfig(proto.Enum): - r"""The supported array value configurations.""" + r"""The supported array value configurations. + + Values: + ARRAY_CONFIG_UNSPECIFIED (0): + The index does not support additional array + queries. + CONTAINS (1): + The index supports array containment queries. + """ ARRAY_CONFIG_UNSPECIFIED = 0 CONTAINS = 1 diff --git a/google/cloud/firestore_admin_v1/types/operation.py b/google/cloud/firestore_admin_v1/types/operation.py index cc15442396..e156130615 100644 --- a/google/cloud/firestore_admin_v1/types/operation.py +++ b/google/cloud/firestore_admin_v1/types/operation.py @@ -36,7 +36,33 @@ class OperationState(proto.Enum): - r"""Describes the state of the operation.""" + r"""Describes the state of the operation. + + Values: + OPERATION_STATE_UNSPECIFIED (0): + Unspecified. + INITIALIZING (1): + Request is being prepared for processing. + PROCESSING (2): + Request is actively being processed. + CANCELLING (3): + Request is in the process of being cancelled + after user called + google.longrunning.Operations.CancelOperation on + the operation. + FINALIZING (4): + Request has been processed and is in its + finalization stage. + SUCCESSFUL (5): + Request has completed successfully. + FAILED (6): + Request has finished being processed, but + encountered an error. + CANCELLED (7): + Request has finished being cancelled after + user called + google.longrunning.Operations.CancelOperation. + """ OPERATION_STATE_UNSPECIFIED = 0 INITIALIZING = 1 PROCESSING = 2 @@ -145,7 +171,16 @@ class IndexConfigDelta(proto.Message): """ class ChangeType(proto.Enum): - r"""Specifies how the index is changing.""" + r"""Specifies how the index is changing. + + Values: + CHANGE_TYPE_UNSPECIFIED (0): + The type of change is not specified or known. + ADD (1): + The single field index is being added. + REMOVE (2): + The single field index is being removed. + """ CHANGE_TYPE_UNSPECIFIED = 0 ADD = 1 REMOVE = 2 @@ -171,7 +206,16 @@ class TtlConfigDelta(proto.Message): """ class ChangeType(proto.Enum): - r"""Specifies how the TTL config is changing.""" + r"""Specifies how the TTL config is changing. + + Values: + CHANGE_TYPE_UNSPECIFIED (0): + The type of change is not specified or known. + ADD (1): + The TTL config is being added. + REMOVE (2): + The TTL config is being removed. + """ CHANGE_TYPE_UNSPECIFIED = 0 ADD = 1 REMOVE = 2 diff --git a/google/cloud/firestore_bundle/types/bundle.py b/google/cloud/firestore_bundle/types/bundle.py index 1da7451a71..21e69fdbaf 100644 --- a/google/cloud/firestore_bundle/types/bundle.py +++ b/google/cloud/firestore_bundle/types/bundle.py @@ -53,6 +53,12 @@ class BundledQuery(proto.Message): class LimitType(proto.Enum): r"""If the query is a limit query, should the limit be applied to the beginning or the end of results. + + Values: + FIRST (0): + + LAST (1): + """ FIRST = 0 LAST = 1 diff --git a/google/cloud/firestore_v1/services/firestore/client.py b/google/cloud/firestore_v1/services/firestore/client.py index a0d903f1f4..f3cf7fe077 100644 --- a/google/cloud/firestore_v1/services/firestore/client.py +++ b/google/cloud/firestore_v1/services/firestore/client.py @@ -1986,7 +1986,7 @@ def sample_create_document(): # Done; return the response. return response - def __enter__(self): + def __enter__(self) -> "FirestoreClient": return self def __exit__(self, type, value, traceback): diff --git a/google/cloud/firestore_v1/types/firestore.py b/google/cloud/firestore_v1/types/firestore.py index bf25616f2e..fddc165f69 100644 --- a/google/cloud/firestore_v1/types/firestore.py +++ b/google/cloud/firestore_v1/types/firestore.py @@ -1421,7 +1421,34 @@ class TargetChange(proto.Message): """ class TargetChangeType(proto.Enum): - r"""The type of change.""" + r"""The type of change. + + Values: + NO_CHANGE (0): + No change has occurred. Used only to send an updated + ``resume_token``. + ADD (1): + The targets have been added. + REMOVE (2): + The targets have been removed. + CURRENT (3): + The targets reflect all changes committed before the targets + were added to the stream. + + This will be sent after or with a ``read_time`` that is + greater than or equal to the time at which the targets were + added. + + Listeners can wait for this change if read-after-write + semantics are desired. + RESET (4): + The targets have been reset, and a new initial state for the + targets will be returned in subsequent changes. + + After the initial state is complete, ``CURRENT`` will be + returned even if the target was previously indicated to be + ``CURRENT``. + """ NO_CHANGE = 0 ADD = 1 REMOVE = 2 diff --git a/google/cloud/firestore_v1/types/query.py b/google/cloud/firestore_v1/types/query.py index 9dc91c7080..1ce7194f1d 100644 --- a/google/cloud/firestore_v1/types/query.py +++ b/google/cloud/firestore_v1/types/query.py @@ -139,7 +139,16 @@ class StructuredQuery(proto.Message): """ class Direction(proto.Enum): - r"""A sort direction.""" + r"""A sort direction. + + Values: + DIRECTION_UNSPECIFIED (0): + Unspecified. + ASCENDING (1): + Ascending. + DESCENDING (2): + Descending. + """ DIRECTION_UNSPECIFIED = 0 ASCENDING = 1 DESCENDING = 2 @@ -227,7 +236,15 @@ class CompositeFilter(proto.Message): """ class Operator(proto.Enum): - r"""A composite filter operator.""" + r"""A composite filter operator. + + Values: + OPERATOR_UNSPECIFIED (0): + Unspecified. This value must not be used. + AND (1): + Documents are required to satisfy all of the + combined filters. + """ OPERATOR_UNSPECIFIED = 0 AND = 1 @@ -255,7 +272,79 @@ class FieldFilter(proto.Message): """ class Operator(proto.Enum): - r"""A field filter operator.""" + r"""A field filter operator. + + Values: + OPERATOR_UNSPECIFIED (0): + Unspecified. This value must not be used. + LESS_THAN (1): + The given ``field`` is less than the given ``value``. + + Requires: + + - That ``field`` come first in ``order_by``. + LESS_THAN_OR_EQUAL (2): + The given ``field`` is less than or equal to the given + ``value``. + + Requires: + + - That ``field`` come first in ``order_by``. + GREATER_THAN (3): + The given ``field`` is greater than the given ``value``. + + Requires: + + - That ``field`` come first in ``order_by``. + GREATER_THAN_OR_EQUAL (4): + The given ``field`` is greater than or equal to the given + ``value``. + + Requires: + + - That ``field`` come first in ``order_by``. + EQUAL (5): + The given ``field`` is equal to the given ``value``. + NOT_EQUAL (6): + The given ``field`` is not equal to the given ``value``. + + Requires: + + - No other ``NOT_EQUAL``, ``NOT_IN``, ``IS_NOT_NULL``, or + ``IS_NOT_NAN``. + - That ``field`` comes first in the ``order_by``. + ARRAY_CONTAINS (7): + The given ``field`` is an array that contains the given + ``value``. + IN (8): + The given ``field`` is equal to at least one value in the + given array. + + Requires: + + - That ``value`` is a non-empty ``ArrayValue`` with at most + 10 values. + - No other ``IN`` or ``ARRAY_CONTAINS_ANY`` or ``NOT_IN``. + ARRAY_CONTAINS_ANY (9): + The given ``field`` is an array that contains any of the + values in the given array. + + Requires: + + - That ``value`` is a non-empty ``ArrayValue`` with at most + 10 values. + - No other ``IN`` or ``ARRAY_CONTAINS_ANY`` or ``NOT_IN``. + NOT_IN (10): + The value of the ``field`` is not in the given array. + + Requires: + + - That ``value`` is a non-empty ``ArrayValue`` with at most + 10 values. + - No other ``IN``, ``ARRAY_CONTAINS_ANY``, ``NOT_IN``, + ``NOT_EQUAL``, ``IS_NOT_NULL``, or ``IS_NOT_NAN``. + - That ``field`` comes first in the ``order_by``. + """ OPERATOR_UNSPECIFIED = 0 LESS_THAN = 1 LESS_THAN_OR_EQUAL = 2 @@ -299,7 +388,32 @@ class UnaryFilter(proto.Message): """ class Operator(proto.Enum): - r"""A unary operator.""" + r"""A unary operator. + + Values: + OPERATOR_UNSPECIFIED (0): + Unspecified. This value must not be used. + IS_NAN (2): + The given ``field`` is equal to ``NaN``. + IS_NULL (3): + The given ``field`` is equal to ``NULL``. + IS_NOT_NAN (4): + The given ``field`` is not equal to ``NaN``. + + Requires: + + - No other ``NOT_EQUAL``, ``NOT_IN``, ``IS_NOT_NULL``, or + ``IS_NOT_NAN``. + - That ``field`` comes first in the ``order_by``. + IS_NOT_NULL (5): + The given ``field`` is not equal to ``NULL``. + + Requires: + + - A single ``NOT_EQUAL``, ``NOT_IN``, ``IS_NOT_NULL``, or + ``IS_NOT_NAN``. + - That ``field`` comes first in the ``order_by``. + """ OPERATOR_UNSPECIFIED = 0 IS_NAN = 2 IS_NULL = 3 diff --git a/google/cloud/firestore_v1/types/write.py b/google/cloud/firestore_v1/types/write.py index e88c906d62..81542639af 100644 --- a/google/cloud/firestore_v1/types/write.py +++ b/google/cloud/firestore_v1/types/write.py @@ -237,7 +237,18 @@ class FieldTransform(proto.Message): """ class ServerValue(proto.Enum): - r"""A value that is calculated by the server.""" + r"""A value that is calculated by the server. + + Values: + SERVER_VALUE_UNSPECIFIED (0): + Unspecified. This value must not be used. + REQUEST_TIME (1): + The time at which the server processed the + request, with millisecond precision. If used on + multiple fields (same or different documents) in + a transaction, all the fields will get the same + server timestamp. + """ SERVER_VALUE_UNSPECIFIED = 0 REQUEST_TIME = 1 From 54c836b5156eec54ce0987f0c4b2894cab06b58b Mon Sep 17 00:00:00 2001 From: "release-please[bot]" <55107282+release-please[bot]@users.noreply.github.com> Date: Mon, 23 Jan 2023 10:52:31 -0500 Subject: [PATCH 2/2] chore(main): release 2.9.1 (#680) Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com> --- .release-please-manifest.json | 2 +- CHANGELOG.md | 12 ++++++++++++ google/cloud/firestore/gapic_version.py | 2 +- google/cloud/firestore_admin_v1/gapic_version.py | 2 +- google/cloud/firestore_bundle/gapic_version.py | 2 +- google/cloud/firestore_v1/gapic_version.py | 2 +- 6 files changed, 17 insertions(+), 5 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 0ce5941abc..1f34b949c5 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.9.0" + ".": "2.9.1" } \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 2aa5055b10..12d16bdab0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,18 @@ [1]: https://pypi.org/project/google-cloud-firestore/#history +## [2.9.1](https://github.com/googleapis/python-firestore/compare/v2.9.0...v2.9.1) (2023-01-20) + + +### Bug Fixes + +* Add context manager return types ([5924bdc](https://github.com/googleapis/python-firestore/commit/5924bdc9c51f3d34f7fa6f350d871688601ecad6)) + + +### Documentation + +* Add documentation for enums ([5924bdc](https://github.com/googleapis/python-firestore/commit/5924bdc9c51f3d34f7fa6f350d871688601ecad6)) + ## [2.9.0](https://github.com/googleapis/python-firestore/compare/v2.8.0...v2.9.0) (2023-01-12) diff --git a/google/cloud/firestore/gapic_version.py b/google/cloud/firestore/gapic_version.py index 60aeb18dbd..18081a7da8 100644 --- a/google/cloud/firestore/gapic_version.py +++ b/google/cloud/firestore/gapic_version.py @@ -13,4 +13,4 @@ # See the License for the specific language governing permissions and # limitations under the License. # -__version__ = "2.9.0" # {x-release-please-version} +__version__ = "2.9.1" # {x-release-please-version} diff --git a/google/cloud/firestore_admin_v1/gapic_version.py b/google/cloud/firestore_admin_v1/gapic_version.py index 60aeb18dbd..18081a7da8 100644 --- a/google/cloud/firestore_admin_v1/gapic_version.py +++ b/google/cloud/firestore_admin_v1/gapic_version.py @@ -13,4 +13,4 @@ # See the License for the specific language governing permissions and # limitations under the License. # -__version__ = "2.9.0" # {x-release-please-version} +__version__ = "2.9.1" # {x-release-please-version} diff --git a/google/cloud/firestore_bundle/gapic_version.py b/google/cloud/firestore_bundle/gapic_version.py index 60aeb18dbd..18081a7da8 100644 --- a/google/cloud/firestore_bundle/gapic_version.py +++ b/google/cloud/firestore_bundle/gapic_version.py @@ -13,4 +13,4 @@ # See the License for the specific language governing permissions and # limitations under the License. # -__version__ = "2.9.0" # {x-release-please-version} +__version__ = "2.9.1" # {x-release-please-version} diff --git a/google/cloud/firestore_v1/gapic_version.py b/google/cloud/firestore_v1/gapic_version.py index 60aeb18dbd..18081a7da8 100644 --- a/google/cloud/firestore_v1/gapic_version.py +++ b/google/cloud/firestore_v1/gapic_version.py @@ -13,4 +13,4 @@ # See the License for the specific language governing permissions and # limitations under the License. # -__version__ = "2.9.0" # {x-release-please-version} +__version__ = "2.9.1" # {x-release-please-version}