From a0e25c8c00391b99a351e667eddc8b4fecad30d8 Mon Sep 17 00:00:00 2001 From: Bu Sun Kim <8822365+busunkim96@users.noreply.github.com> Date: Mon, 18 Oct 2021 17:30:13 -0600 Subject: [PATCH] fix: list oneofs in docstring (#1030) * fix: list oneofs in docstring * chore: copy to ads templates * docs: remove separate list in docstring * chore: also update ads --- .../%name/%version/%sub/types/_message.py.j2 | 15 ++++++++ .../%name_%version/%sub/types/_message.py.j2 | 15 ++++++++ .../cloud/asset_v1/types/asset_service.py | 36 +++++++++++++++++++ .../google/cloud/asset_v1/types/assets.py | 19 ++++++++++ .../cloud/logging_v2/types/log_entry.py | 10 ++++++ .../cloud/logging_v2/types/logging_config.py | 4 +++ .../cloud/redis_v1/types/cloud_redis.py | 6 ++++ 7 files changed, 105 insertions(+) diff --git a/gapic/ads-templates/%namespace/%name/%version/%sub/types/_message.py.j2 b/gapic/ads-templates/%namespace/%name/%version/%sub/types/_message.py.j2 index 581c976b5e..32fb35672d 100644 --- a/gapic/ads-templates/%namespace/%name/%version/%sub/types/_message.py.j2 +++ b/gapic/ads-templates/%namespace/%name/%version/%sub/types/_message.py.j2 @@ -2,10 +2,25 @@ class {{ message.name }}({{ p }}.Message): r"""{{ message.meta.doc|rst(indent=4) }} {% if message.fields|length %} + {# Only include note if a oneof has more than one member field. #} + {% if message.oneof_fields() %} + {% if message.oneof_fields().values() | map('length') | max > 1 %} + This message has `oneof`_ fields (mutually exclusive fields). + For each oneof, at most one member field can be set at the same time. + Setting any member of the oneof automatically clears all other + members. + + {% endif %} + .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields + + {% endif %} Attributes: {% for field in message.fields.values() %} {{ field.name }} ({{ field.ident.sphinx }}): {{ field.meta.doc|rst(indent=12, nl=False) }} + {% if field.oneof %} + This field is a member of `oneof`_ ``{{ field.oneof }}``. + {% endif %} {% endfor %} {% endif %} """ diff --git a/gapic/templates/%namespace/%name_%version/%sub/types/_message.py.j2 b/gapic/templates/%namespace/%name_%version/%sub/types/_message.py.j2 index 9bd6d51d82..11e6b129be 100644 --- a/gapic/templates/%namespace/%name_%version/%sub/types/_message.py.j2 +++ b/gapic/templates/%namespace/%name_%version/%sub/types/_message.py.j2 @@ -2,10 +2,25 @@ class {{ message.name }}({{ p }}.Message): r"""{{ message.meta.doc|rst(indent=4) }} {% if message.fields|length %} + {# Only include note if a oneof has more than one member field. #} + {% if message.oneof_fields() %} + {% if message.oneof_fields().values() | map('length') | max > 1 %} + This message has `oneof`_ fields (mutually exclusive fields). + For each oneof, at most one member field can be set at the same time. + Setting any member of the oneof automatically clears all other + members. + + {% endif %} + .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields + + {% endif %} Attributes: {% for field in message.fields.values() %} {{ field.name }} ({{ field.ident.sphinx }}): {{ field.meta.doc|rst(indent=12, nl=False) }} + {% if field.oneof %} + This field is a member of `oneof`_ ``{{ field.oneof }}``. + {% endif %} {% endfor %} {% endif %} """ diff --git a/tests/integration/goldens/asset/google/cloud/asset_v1/types/asset_service.py b/tests/integration/goldens/asset/google/cloud/asset_v1/types/asset_service.py index 739d78d9a1..0d028e2bf7 100644 --- a/tests/integration/goldens/asset/google/cloud/asset_v1/types/asset_service.py +++ b/tests/integration/goldens/asset/google/cloud/asset_v1/types/asset_service.py @@ -512,13 +512,22 @@ class DeleteFeedRequest(proto.Message): class OutputConfig(proto.Message): r"""Output configuration for export assets destination. + This message has `oneof`_ fields (mutually exclusive fields). + For each oneof, at most one member field can be set at the same time. + Setting any member of the oneof automatically clears all other + members. + + .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields + Attributes: gcs_destination (google.cloud.asset_v1.types.GcsDestination): Destination on Cloud Storage. + This field is a member of `oneof`_ ``destination``. bigquery_destination (google.cloud.asset_v1.types.BigQueryDestination): Destination on BigQuery. The output table stores the fields in asset proto as columns in BigQuery. + This field is a member of `oneof`_ ``destination``. """ gcs_destination = proto.Field( @@ -538,9 +547,12 @@ class OutputConfig(proto.Message): class OutputResult(proto.Message): r"""Output result of export assets. + .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields + Attributes: gcs_result (google.cloud.asset_v1.types.GcsOutputResult): Export result on Cloud Storage. + This field is a member of `oneof`_ ``result``. """ gcs_result = proto.Field( @@ -569,6 +581,13 @@ class GcsOutputResult(proto.Message): class GcsDestination(proto.Message): r"""A Cloud Storage location. + This message has `oneof`_ fields (mutually exclusive fields). + For each oneof, at most one member field can be set at the same time. + Setting any member of the oneof automatically clears all other + members. + + .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields + Attributes: uri (str): The uri of the Cloud Storage object. It's the same uri that @@ -581,6 +600,7 @@ class GcsDestination(proto.Message): there is no `hold `__, it will be overwritten with the exported result. + This field is a member of `oneof`_ ``object_uri``. uri_prefix (str): The uri prefix of all generated Cloud Storage objects. Example: "gs://bucket_name/object_name_prefix". Each object @@ -591,6 +611,7 @@ class GcsDestination(proto.Message): compute.googleapis.com/Disk assets. An INVALID_ARGUMENT error will be returned if file with the same name "gs://bucket_name/object_name_prefix" already exists. + This field is a member of `oneof`_ ``object_uri``. """ uri = proto.Field( @@ -751,9 +772,12 @@ class PubsubDestination(proto.Message): class FeedOutputConfig(proto.Message): r"""Output configuration for asset feed destination. + .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields + Attributes: pubsub_destination (google.cloud.asset_v1.types.PubsubDestination): Destination on Pub/Sub. + This field is a member of `oneof`_ ``destination``. """ pubsub_destination = proto.Field( @@ -1420,12 +1444,15 @@ class Options(proto.Message): class ConditionContext(proto.Message): r"""The IAM conditions context. + .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields + Attributes: access_time (google.protobuf.timestamp_pb2.Timestamp): The hypothetical access timestamp to evaluate IAM conditions. Note that this value must not be earlier than the current time; otherwise, an INVALID_ARGUMENT error will be returned. + This field is a member of `oneof`_ ``TimeContext``. """ access_time = proto.Field( @@ -1580,11 +1607,20 @@ class IamPolicyAnalysisOutputConfig(proto.Message): r"""Output configuration for export IAM policy analysis destination. + This message has `oneof`_ fields (mutually exclusive fields). + For each oneof, at most one member field can be set at the same time. + Setting any member of the oneof automatically clears all other + members. + + .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields + Attributes: gcs_destination (google.cloud.asset_v1.types.IamPolicyAnalysisOutputConfig.GcsDestination): Destination on Cloud Storage. + This field is a member of `oneof`_ ``destination``. bigquery_destination (google.cloud.asset_v1.types.IamPolicyAnalysisOutputConfig.BigQueryDestination): Destination on BigQuery. + This field is a member of `oneof`_ ``destination``. """ class GcsDestination(proto.Message): diff --git a/tests/integration/goldens/asset/google/cloud/asset_v1/types/assets.py b/tests/integration/goldens/asset/google/cloud/asset_v1/types/assets.py index ef30863e3c..40a0faf93c 100644 --- a/tests/integration/goldens/asset/google/cloud/asset_v1/types/assets.py +++ b/tests/integration/goldens/asset/google/cloud/asset_v1/types/assets.py @@ -131,6 +131,13 @@ class Asset(proto.Message): types `__ for more information. + This message has `oneof`_ fields (mutually exclusive fields). + For each oneof, at most one member field can be set at the same time. + Setting any member of the oneof automatically clears all other + members. + + .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields + Attributes: update_time (google.protobuf.timestamp_pb2.Timestamp): The last update timestamp of an asset. update_time is @@ -171,12 +178,15 @@ class Asset(proto.Message): access_policy (google.identity.accesscontextmanager.v1.access_policy_pb2.AccessPolicy): Please also refer to the `access policy user guide `__. + This field is a member of `oneof`_ ``access_context_policy``. access_level (google.identity.accesscontextmanager.v1.access_level_pb2.AccessLevel): Please also refer to the `access level user guide `__. + This field is a member of `oneof`_ ``access_context_policy``. service_perimeter (google.identity.accesscontextmanager.v1.service_perimeter_pb2.ServicePerimeter): Please also refer to the `service perimeter user guide `__. + This field is a member of `oneof`_ ``access_context_policy``. os_inventory (google.cloud.osconfig.v1.inventory_pb2.Inventory): A representation of runtime OS Inventory information. See `this @@ -882,11 +892,20 @@ class Resource(proto.Message): class Access(proto.Message): r"""An IAM role or permission under analysis. + This message has `oneof`_ fields (mutually exclusive fields). + For each oneof, at most one member field can be set at the same time. + Setting any member of the oneof automatically clears all other + members. + + .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields + Attributes: role (str): The role. + This field is a member of `oneof`_ ``oneof_access``. permission (str): The permission. + This field is a member of `oneof`_ ``oneof_access``. analysis_state (google.cloud.asset_v1.types.IamPolicyAnalysisState): The analysis state of this access. """ diff --git a/tests/integration/goldens/logging/google/cloud/logging_v2/types/log_entry.py b/tests/integration/goldens/logging/google/cloud/logging_v2/types/log_entry.py index 18822503d9..96cfd0f403 100644 --- a/tests/integration/goldens/logging/google/cloud/logging_v2/types/log_entry.py +++ b/tests/integration/goldens/logging/google/cloud/logging_v2/types/log_entry.py @@ -36,6 +36,13 @@ class LogEntry(proto.Message): r"""An individual entry in a log. + This message has `oneof`_ fields (mutually exclusive fields). + For each oneof, at most one member field can be set at the same time. + Setting any member of the oneof automatically clears all other + members. + + .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields + Attributes: log_name (str): Required. The resource name of the log to which this log @@ -84,12 +91,15 @@ class LogEntry(proto.Message): "type.googleapis.com/google.cloud.audit.AuditLog" "type.googleapis.com/google.appengine.logging.v1.RequestLog". + This field is a member of `oneof`_ ``payload``. text_payload (str): The log entry payload, represented as a Unicode string (UTF-8). + This field is a member of `oneof`_ ``payload``. json_payload (google.protobuf.struct_pb2.Struct): The log entry payload, represented as a structure that is expressed as a JSON object. + This field is a member of `oneof`_ ``payload``. timestamp (google.protobuf.timestamp_pb2.Timestamp): Optional. The time the event described by the log entry occurred. This time is used to compute the log entry's age diff --git a/tests/integration/goldens/logging/google/cloud/logging_v2/types/logging_config.py b/tests/integration/goldens/logging/google/cloud/logging_v2/types/logging_config.py index 1122a62009..fd04767f02 100644 --- a/tests/integration/goldens/logging/google/cloud/logging_v2/types/logging_config.py +++ b/tests/integration/goldens/logging/google/cloud/logging_v2/types/logging_config.py @@ -195,6 +195,9 @@ class LogSink(proto.Message): created within a project, organization, billing account, or folder. + + .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields + Attributes: name (str): Required. The client-assigned sink identifier, unique within @@ -279,6 +282,7 @@ class LogSink(proto.Message): bigquery_options (google.cloud.logging_v2.types.BigQueryOptions): Optional. Options that affect sinks exporting data to BigQuery. + This field is a member of `oneof`_ ``options``. create_time (google.protobuf.timestamp_pb2.Timestamp): Output only. The creation timestamp of the sink. diff --git a/tests/integration/goldens/redis/google/cloud/redis_v1/types/cloud_redis.py b/tests/integration/goldens/redis/google/cloud/redis_v1/types/cloud_redis.py index 793fa802c0..3448acb649 100644 --- a/tests/integration/goldens/redis/google/cloud/redis_v1/types/cloud_redis.py +++ b/tests/integration/goldens/redis/google/cloud/redis_v1/types/cloud_redis.py @@ -501,10 +501,13 @@ class GcsSource(proto.Message): class InputConfig(proto.Message): r"""The input content + .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields + Attributes: gcs_source (google.cloud.redis_v1.types.GcsSource): Google Cloud Storage location where input content is located. + This field is a member of `oneof`_ ``source``. """ gcs_source = proto.Field( @@ -558,10 +561,13 @@ class GcsDestination(proto.Message): class OutputConfig(proto.Message): r"""The output content + .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields + Attributes: gcs_destination (google.cloud.redis_v1.types.GcsDestination): Google Cloud Storage destination for output content. + This field is a member of `oneof`_ ``destination``. """ gcs_destination = proto.Field(