Skip to content

Commit

Permalink
docs: update docstrings (via synth) (#19)
Browse files Browse the repository at this point in the history
  • Loading branch information
yoshi-automation authored Mar 17, 2020
1 parent e2e4f7b commit 4d74fd3
Show file tree
Hide file tree
Showing 16 changed files with 366 additions and 268 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -215,10 +215,12 @@ def export_assets(
metadata=None,
):
"""
Exports assets with time and resource types to a given Cloud Storage
location. The output format is newline-delimited JSON. This API
implements the ``google.longrunning.Operation`` API allowing you to keep
track of the export.
Additional information regarding long-running operations. In
particular, this specifies the types that are returned from long-running
operations.
Required for methods that return ``google.longrunning.Operation``;
invalid otherwise.
Example:
>>> from google.cloud import asset_v1
Expand Down Expand Up @@ -338,12 +340,10 @@ def batch_get_assets_history(
metadata=None,
):
"""
Batch gets the update history of assets that overlap a time window.
For RESOURCE content, this API outputs history with asset in both
non-delete or deleted status. For IAM_POLICY content, this API outputs
history when the asset and its attached IAM POLICY both exist. This can
create gaps in the output history. If a specified asset does not exist,
this API returns an INVALID_ARGUMENT error.
JSON name of this field. The value is set by protocol compiler. If
the user has set a "json_name" option on this field, that option's value
will be used. Otherwise, it's deduced from the field's name by
converting it to camelCase.
Example:
>>> from google.cloud import asset_v1
Expand All @@ -367,25 +367,22 @@ def batch_get_assets_history(
organization number (such as "organizations/123"), a project ID (such as
"projects/my-project-id")", or a project number (such as "projects/12345").
content_type (~google.cloud.asset_v1.types.ContentType): Optional. The content type.
read_time_window (Union[dict, ~google.cloud.asset_v1.types.TimeWindow]): Optional. The time window for the asset history. Both start_time and
end_time are optional and if set, it must be after 2018-10-02 UTC. If
end_time is not set, it is default to current timestamp. If start_time
is not set, the snapshot of the assets at end_time will be returned. The
returned results contain all temporal assets whose time window overlap
with read_time_window.
read_time_window (Union[dict, ~google.cloud.asset_v1.types.TimeWindow]): Manages long-running operations with an API service.
When an API method normally takes long time to complete, it can be
designed to return ``Operation`` to the client, and the client can use
this interface to receive the real response asynchronously by polling
the operation resource, or pass the operation resource to another API
(such as Google Cloud Pub/Sub API) to receive the response. Any API
service that returns long-running operations should implement the
``Operations`` interface so developers can have a consistent client
experience.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.asset_v1.types.TimeWindow`
asset_names (list[str]): A list of the full names of the assets. For example:
``//compute.googleapis.com/projects/my_project_123/zones/zone1/instances/instance1``.
See `Resource
Names <https://cloud.google.com/apis/design/resource_names#full_resource_name>`__
and `Resource Name
Format <https://cloud.google.com/asset-inventory/docs/resource-name-format>`__
for more info.
The request becomes a no-op if the asset name list is empty, and the max
size of the asset name list is 100 in one request.
asset_names (list[str]): The resource has one pattern, but the API owner expects to add more
later. (This is the inverse of ORIGINALLY_SINGLE_PATTERN, and prevents
that from being necessary once there are multiple patterns.)
retry (Optional[google.api_core.retry.Retry]): A retry object used
to retry requests. If ``None`` is specified, requests will
be retried using a default configuration.
Expand Down Expand Up @@ -476,11 +473,37 @@ def create_feed(
"projects/12345").
feed_id (str): Required. This is the client-assigned asset feed identifier and it needs to
be unique under a specific parent project/folder/organization.
feed (Union[dict, ~google.cloud.asset_v1.types.Feed]): Required. The feed details. The field ``name`` must be empty and it
will be generated in the format of:
projects/project_number/feeds/feed_id
folders/folder_number/feeds/feed_id
organizations/organization_number/feeds/feed_id
feed (Union[dict, ~google.cloud.asset_v1.types.Feed]): Each of the definitions above may have "options" attached. These are
just annotations which may cause code to be generated slightly
differently or may contain hints for code that manipulates protocol
messages.
Clients may define custom options as extensions of the \*Options
messages. These extensions may not yet be known at parsing time, so the
parser cannot store the values in them. Instead it stores them in a
field in the \*Options message called uninterpreted_option. This field
must have the same name across all \*Options messages. We then use this
field to populate the extensions when we build a descriptor, at which
point all protos have been parsed and so all extensions are known.
Extension numbers for custom options may be chosen as follows:
- For options which will only be used within a single application or
organization, or for experimental options, use field numbers 50000
through 99999. It is up to you to ensure that you do not use the same
number for multiple options.
- For options which will be published and used publicly by multiple
independent entities, e-mail
protobuf-global-extension-registry@google.com to reserve extension
numbers. Simply provide your project name (e.g. Objective-C plugin)
and your project website (if available) -- there's no need to explain
how you intend to use them. Usually you only need one extension
number. You can declare multiple options with only one extension
number by putting them in a sub-message. See the Custom Options
section of the docs for examples:
https://developers.google.com/protocol-buffers/docs/proto#options If
this turns out to be popular, a web service will be set up to
automatically assign option numbers.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.asset_v1.types.Feed`
Expand Down Expand Up @@ -554,10 +577,16 @@ def get_feed(
>>> response = client.get_feed(name)
Args:
name (str): Required. The name of the Feed and it must be in the format of:
projects/project_number/feeds/feed_id
folders/folder_number/feeds/feed_id
organizations/organization_number/feeds/feed_id
name (str): The resource type. It must be in the format of
{service_name}/{resource_type_kind}. The ``resource_type_kind`` must be
singular and must not include version numbers.
Example: ``storage.googleapis.com/Bucket``
The value of the resource_type_kind must follow the regular expression
/[A-Za-z][a-zA-Z0-9]+/. It should start with an upper case character and
should use PascalCase (UpperCamelCase). The maximum number of characters
allowed for the ``resource_type_kind`` is 100.
retry (Optional[google.api_core.retry.Retry]): A retry object used
to retry requests. If ``None`` is specified, requests will
be retried using a default configuration.
Expand Down Expand Up @@ -703,17 +732,36 @@ def update_feed(
>>> response = client.update_feed(feed, update_mask)
Args:
feed (Union[dict, ~google.cloud.asset_v1.types.Feed]): Required. The new values of feed details. It must match an existing
feed and the field ``name`` must be in the format of:
projects/project_number/feeds/feed_id or
folders/folder_number/feeds/feed_id or
organizations/organization_number/feeds/feed_id.
feed (Union[dict, ~google.cloud.asset_v1.types.Feed]): See ``HttpRule``.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.asset_v1.types.Feed`
update_mask (Union[dict, ~google.cloud.asset_v1.types.FieldMask]): Required. Only updates the ``feed`` fields indicated by this mask.
The field mask must not be empty, and it must not contain fields that
are immutable or only set by the server.
update_mask (Union[dict, ~google.cloud.asset_v1.types.FieldMask]): A URL/resource name that uniquely identifies the type of the
serialized protocol buffer message. This string must contain at least
one "/" character. The last segment of the URL's path must represent the
fully qualified name of the type (as in
``path/google.protobuf.Duration``). The name should be in a canonical
form (e.g., leading "." is not accepted).
In practice, teams usually precompile into the binary all types that
they expect it to use in the context of Any. However, for URLs which use
the scheme ``http``, ``https``, or no scheme, one can optionally set up
a type server that maps type URLs to message definitions as follows:
- If no scheme is provided, ``https`` is assumed.
- An HTTP GET on the URL must yield a ``google.protobuf.Type`` value in
binary format, or produce an error.
- Applications are allowed to cache lookup results based on the URL, or
have them precompiled into a binary to avoid any lookup. Therefore,
binary compatibility needs to be preserved on changes to types. (Use
versioned type names to manage breaking changes.)
Note: this functionality is not currently available in the official
protobuf release, and it is not used for type URLs beginning with
type.googleapis.com.
Schemes other than ``http``, ``https`` (or the empty scheme) might be
used with implementation specific semantics.
If a dict is provided, it must be of the same form as the protobuf
message :class:`~google.cloud.asset_v1.types.FieldMask`
Expand Down Expand Up @@ -787,10 +835,16 @@ def delete_feed(
>>> client.delete_feed(name)
Args:
name (str): Required. The name of the feed and it must be in the format of:
projects/project_number/feeds/feed_id
folders/folder_number/feeds/feed_id
organizations/organization_number/feeds/feed_id
name (str): A list of the full names of the assets. For example:
``//compute.googleapis.com/projects/my_project_123/zones/zone1/instances/instance1``.
See `Resource
Names <https://cloud.google.com/apis/design/resource_names#full_resource_name>`__
and `Resource Name
Format <https://cloud.google.com/asset-inventory/docs/resource-name-format>`__
for more info.
The request becomes a no-op if the asset name list is empty, and the max
size of the asset name list is 100 in one request.
retry (Optional[google.api_core.retry.Retry]): A retry object used
to retry requests. If ``None`` is specified, requests will
be retried using a default configuration.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,10 +40,10 @@ class ContentType(enum.IntEnum):

class NullValue(enum.IntEnum):
"""
``NullValue`` is a singleton enumeration to represent the null value
for the ``Value`` type union.
The JSON representation for ``NullValue`` is JSON ``null``.
Required. The name of the Feed and it must be in the format of:
projects/project_number/feeds/feed_id
folders/folder_number/feeds/feed_id
organizations/organization_number/feeds/feed_id
Attributes:
NULL_VALUE (int): Null value.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -119,10 +119,12 @@ def channel(self):
def export_assets(self):
"""Return the gRPC stub for :meth:`AssetServiceClient.export_assets`.
Exports assets with time and resource types to a given Cloud Storage
location. The output format is newline-delimited JSON. This API
implements the ``google.longrunning.Operation`` API allowing you to keep
track of the export.
Additional information regarding long-running operations. In
particular, this specifies the types that are returned from long-running
operations.
Required for methods that return ``google.longrunning.Operation``;
invalid otherwise.
Returns:
Callable: A callable which accepts the appropriate
Expand All @@ -135,12 +137,10 @@ def export_assets(self):
def batch_get_assets_history(self):
"""Return the gRPC stub for :meth:`AssetServiceClient.batch_get_assets_history`.
Batch gets the update history of assets that overlap a time window.
For RESOURCE content, this API outputs history with asset in both
non-delete or deleted status. For IAM_POLICY content, this API outputs
history when the asset and its attached IAM POLICY both exist. This can
create gaps in the output history. If a specified asset does not exist,
this API returns an INVALID_ARGUMENT error.
JSON name of this field. The value is set by protocol compiler. If
the user has set a "json_name" option on this field, that option's value
will be used. Otherwise, it's deduced from the field's name by
converting it to camelCase.
Returns:
Callable: A callable which accepts the appropriate
Expand Down

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit 4d74fd3

Please sign in to comment.