Skip to content

Commit

Permalink
fix: list oneofs in docstring (#1030)
Browse files Browse the repository at this point in the history 
* fix: list oneofs in docstring

* chore: copy to ads templates

* docs: remove separate list in docstring

* chore: also update ads
  • Loading branch information
@busunkim96
busunkim96 committed Oct 18, 2021
1 parent 582fed9 commit a0e25c8
Show file tree
Hide file tree
Showing 7 changed files with 105 additions and 0 deletions.
15 changes: 15 additions & 0 deletions gapic/ads-templates/%namespace/%name/%version/%sub/types/_message.py.j2
View file
Expand Up @@ -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 %}
"""
Expand Down
15 changes: 15 additions & 0 deletions gapic/templates/%namespace/%name_%version/%sub/types/_message.py.j2
View file
Expand Up @@ -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 %}
"""
Expand Down
36 changes: 36 additions & 0 deletions tests/integration/goldens/asset/google/cloud/asset_v1/types/asset_service.py
View file
Expand Up @@ -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(
Expand All @@ -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(
Expand Down Expand Up @@ -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
Expand All @@ -581,6 +600,7 @@ class GcsDestination(proto.Message):
there is no
`hold <https://cloud.google.com/storage/docs/object-holds>`__,
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
Expand All @@ -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(
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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):
Expand Down
19 changes: 19 additions & 0 deletions tests/integration/goldens/asset/google/cloud/asset_v1/types/assets.py
View file
Expand Up @@ -131,6 +131,13 @@ class Asset(proto.Message):
types <https://cloud.google.com/asset-inventory/docs/supported-asset-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
Expand Down Expand Up @@ -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 <https://cloud.google.com/access-context-manager/docs/overview#access-policies>`__.
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 <https://cloud.google.com/access-context-manager/docs/overview#access-levels>`__.
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 <https://cloud.google.com/vpc-service-controls/docs/overview>`__.
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
Expand Down Expand Up @@ -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.
"""
Expand Down
10 changes: 10 additions & 0 deletions tests/integration/goldens/logging/google/cloud/logging_v2/types/log_entry.py
View file
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions tests/integration/goldens/logging/google/cloud/logging_v2/types/logging_config.py
View file
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
6 changes: 6 additions & 0 deletions tests/integration/goldens/redis/google/cloud/redis_v1/types/cloud_redis.py
View file
Expand Up @@ -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(
Expand Down Expand Up @@ -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(
Expand Down

0 comments on commit a0e25c8

Please sign in to comment.